Merge pull request Badgerati#628 from Badgerati/develop

v2.0.0

.github/CONTRIBUTING.md

@@ -13,6 +13,7 @@ The following is a set of guidelines for contributing to Pode on GitHub. These a
   * [Issues](#issues)
   * [Branch Names](#branch-names)
   * [Pull Requests](#pull-requests)
+  * [Building](#building)
   * [Testing](#testing)
   * [Documentation](#documentation)
 * [Styleguide](#styleguide)
@@ -38,7 +39,9 @@ If you have a question, feel free to either ask it on [GitHub Issues](https://gi
 
 ## About Pode
 
-Pode is a PowerShell framework, and the aim is to make it purely PowerShell only with *no* external dependencies. This allows Pode to be very lightweight, and just work out-of-the-box when the module is installed on any platform.
+Pode is a PowerShell framework/web server. The aim is to make it purely PowerShell, with *no* external dependencies - other than what is available in .NET Core. This allows Pode to be very lightweight, and just work out-of-the-box when the module is installed on any platform.
+
+The only current exception to the "all PowerShell" rule is the socket listener Pode uses. This listener is a part of Pode, but is written in .NET Core.
 
 ## How to Contribute
 
@@ -65,15 +68,23 @@ When you open a new Pull Request, please ensure:
 
 Once opened GitHub will automatically run CI on Windows, Linux and MacOS, as well as Code Coverage.
 
+### Building
+
+Before running any of Pode's examples, you will need to compile the Listener first. To do so you will need [`Invoke-Build`](https://github.com/nightroman/Invoke-Build). Once installed, run the following:
+
+```powershell
+Invoke-Build Build
+```
+
 ### Testing
 
-Pode has Unit Tests, there are also some Performance Tests but you do not need to worry about them. There are also currently no Integration Tests.
+Pode has Unit and Integration Tests, there are also some Performance Tests but you do not need to worry about them.
 
-Where possible, please try to create/update new Unit Tests especially for features. Don't worry too much about decreasing the Code Coverage.
+Where possible, please try to create/update new Unit/Integration Tests especially for features. Don't worry too much about decreasing the Code Coverage.
 
-The Unit Tests can be found at `/tests/unit/` from the root of the repository.
+The Unit Tests can be found at `/tests/unit/` from the root of the repository, and the Integration Tests can be found at `tests/integration`.
 
-To run the tests, you will need [`Invoke-Build`](https://github.com/nightroman/Invoke-Build). Once installed, run the following to run the tests:
+To run the tests, you will need [`Invoke-Build`](https://github.com/nightroman/Invoke-Build) (running the tests will compile Pode's listener). Once installed, run the following to run the tests:
 
 ```powershell
 Invoke-Build Test

.github/workflows/ci-coverage.yml

@@ -27,7 +27,7 @@ jobs:
       shell: pwsh
       env:
         PODE_COVERALLS_TOKEN: ${{ secrets.PODE_COVERALLS_TOKEN }}
-        PODE_RUN_CODE_COVERAGE: true
+        PODE_RUN_CODE_COVERAGE: false
       run: |
         [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
         Invoke-Build Test

.gitignore

@@ -6,6 +6,7 @@ pode_modules/
 ps_modules/
 docs/[Ff]unctions/
 examples/state.json
+pkg/
 
 
 # Code Runner
@@ -31,6 +32,7 @@ bld/
 [Tt]emp/
 [Ll]ogs/
 [Ss]ite/
+[Ll]ibs/
 
 # Packing Artifacts
 *.zip

Dockerfile

@@ -1,4 +1,4 @@
 FROM mcr.microsoft.com/powershell:7.0.1-ubuntu-16.04
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
-COPY ./src/ /usr/local/share/powershell/Modules/Pode
+COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

README.md

@@ -10,7 +10,7 @@
 [![PowerShell](https://img.shields.io/powershellgallery/dt/pode.svg?label=PowerShell&colorB=085298)](https://www.powershellgallery.com/packages/Pode)
 [![Docker](https://img.shields.io/docker/pulls/badgerati/pode.svg?label=Docker)](https://hub.docker.com/r/badgerati/pode/)
 
-Pode is a Cross-Platform framework, *completely written in PowerShell*, for creating web servers to host [REST APIs](https://badgerati.github.io/Pode/Tutorials/Routes/Overview/), [Web Pages](https://badgerati.github.io/Pode/Tutorials/Routes/Examples/WebPages/), and [SMTP/TCP](https://badgerati.github.io/Pode/Hosting/SmtpServer/) Servers. Pode also allows you to render dynamic files using [`.pode`](https://badgerati.github.io/Pode/Tutorials/Views/Pode/) files, which are just embedded PowerShell, or other [Third-Party](https://badgerati.github.io/Pode/Tutorials/Views/ThirdParty/) template engines. Plus many more features, including [Azure Functions](https://badgerati.github.io/Pode/Hosting/AzureFunctions/) and [AWS Lambda](https://badgerati.github.io/Pode/Hosting/AwsLambda/) support!
+Pode is a Cross-Platform framework for creating web servers to host [REST APIs](https://badgerati.github.io/Pode/Tutorials/Routes/Overview/), [Web Pages](https://badgerati.github.io/Pode/Tutorials/Routes/Examples/WebPages/), and [SMTP/TCP](https://badgerati.github.io/Pode/Hosting/SmtpServer/) Servers. Pode also allows you to render dynamic files using [`.pode`](https://badgerati.github.io/Pode/Tutorials/Views/Pode/) files, which are just embedded PowerShell, or other [Third-Party](https://badgerati.github.io/Pode/Tutorials/Views/ThirdParty/) template engines. Plus many more features, including [Azure Functions](https://badgerati.github.io/Pode/Hosting/AzureFunctions/) and [AWS Lambda](https://badgerati.github.io/Pode/Hosting/AwsLambda/) support!
 
 <p align="center">
     <img src="https://github.com/Badgerati/Pode/blob/develop/images/example_code_2.png?raw=true" />
@@ -52,9 +52,9 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Ability to allow/deny requests from certain IP addresses and subnets
 * Basic rate limiting for IP addresses and subnets
 * Middleware and Sessions on web servers, with Flash message and CSRF support
-* Authentication on requests, such as Basic and Windows Active Directory
+* Authentication on requests, such as Basic, Windows and Azure AD
 * Support for dynamically building Routes from Functions and Modules
-* (Windows) Generate/bind self-signed certificates, and signed certificates
+* Generate/bind self-signed certificates
 * (Windows) Open the hosted server as a desktop application
 
 ## Install
@@ -78,10 +78,16 @@ docker pull badgerati/pode
 
 Pull Requests, Bug Reports and Feature Requests are welcome! Feel free to help out with Issues and Projects!
 
-To run the unit tests, run the following command from the root of the repository (this will auto-install Pester for you):
+To run the unit tests, run the following command from the root of the repository (this will build Pode and, if needed, auto-install Pester/.NET Core):
 
 ```powershell
 Invoke-Build Test
 ```
 
+To just build Pode, before running any examples, run the following:
+
+```powershell
+Invoke-Build Build
+```
+
 To work on issues you can fork Pode, and then open a Pull Request for approval. Pull Requests should be made against the `develop` branch. Each Pull Request should also have an appropriate issue created.

arm32.dockerfile

@@ -1,4 +1,4 @@
 FROM badgerati/ps-core:7.0.1-arm32
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
-COPY ./src/ /usr/local/share/powershell/Modules/Pode
+COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

docs/Getting-Started/FirstApp.md

@@ -30,6 +30,12 @@ Success, saved package.json
 
 ## REST Server
 
+* Although not required, it is recommended to import the Pode module using a maximum version, to avoid any breaking changes from new major versions:
+
+```powershell
+Import-Module -Name Pode -MaximumVersion 2.99.99 -Force
+```
+
 * Within your `server.ps1` file, first you need to start the Server. This is where the main script will go that defines how the server should function:
 
 ```powershell

docs/Getting-Started/KnownIssues.md

@@ -76,3 +76,16 @@ function New-UnboundClassInstance([Type]$type, [object[]]$arguments = $null)
 Import-Module '<path>\CreateClassInstanceHelper.psm1'
 New-UnboundClassInstance([Foo], $argsForCtor)
 ```
+
+## Certificates
+
+For HTTPS there are a few issues you may run into, and to resolve them you can use the below:
+
+* On Windows, you may need to install the certificate into your Trusted Root on the Local Machine (mostly for self-signed certificates).
+* You may be required to run the following, to force TLS1.2, before making web requests:
+
+```powershell
+[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
+```
+
+* On *nix platforms, for self-signed certificates, you may need to use `-SkipCertificateCheck` on `Invoke-WebRequest` and `Invoke-RestMethod`.

docs/Getting-Started/LocalModules.md

@@ -59,4 +59,6 @@ package.json
 
 ## Importing
 
-When the modules have been downloaded, you can utilise them using the  [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function.
+When the modules have been downloaded, you can import them using the [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function.
+
+Unlike `Import-Module`, [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) will check if some module is within the `ps_modules` directory first, then it will check the global modules.