Badgerati#376: Add documentation

SigitasPersonal · Sep 24, 2019 · 9254946 · 9254946
1 parent 2cb5717
commit 9254946
Show file tree

Hide file tree

Showing 6 changed files with 110 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Docker support, including images for ARM/Raspberry Pi
 * Azure Functions and AWS Lambda support
 * Listen on a single or multiple IP address/hostnames
-* Support for HTTP, HTTPS, TCP and SMTP
+* Support for HTTP, HTTPS, TCP and SMTP (Experimental cross-platform support for HTTPS)
 * Host REST APIs, Web Pages, and Static Content (with caching)
 * Support for custom error pages
 * Multi-thread support for incoming requests

diff --git a/docs/Tutorials/Certificates.md b/docs/Tutorials/Certificates.md
@@ -2,8 +2,9 @@
 
 !!! warning
     Binding existing, and generating self-signed certificates is only supported on *Windows*.
+    For cross-platform HTTPS support [see here](../PodeServer).
 
-Pode has the ability to generate and bind self-signed certificates (for dev/testing), as well as the ability to bind existing - already installed - certificates for HTTPS. If Pode detects that the `IP:Port` or `Hostname:Port` binding already has a certificate bound, then Pode will re-use that certificate and will not create a new self-signed certificate, or bind a new certificate.
+Pode has the ability to generate and bind self-signed certificates (for dev/testing), as well as the ability to bind existing - already installed - certificates for HTTPS on Windows, using the default Server type. If Pode detects that the `IP:Port` or `Hostname:Port` binding already has a certificate bound, then Pode will re-use that certificate and will not create a new self-signed certificate, or bind a new certificate.
 
 ## Self-Signed
 

diff --git a/docs/Tutorials/PodeServer.md b/docs/Tutorials/PodeServer.md
@@ -0,0 +1,100 @@
+# Pode Server
+
+!!! notice
+    The Pode server type uses sockets to allow cross-platform support for HTTPS. This server type is also **experimental**.
+
+The Pode server type, as specified above, is an experimental type that uses sockets to allow for cross-platform support of HTTPS (it does also support normal HTTP!).
+
+To start using this server type, there isn't very must you need to do. All that's really required is to set the `-Type` on [`Start-PodeServer`](../../Functions/Core/Start-PodeServer), and to supply a certificate on [`Add-PodeEndpoint`](../../Functions/Core/Add-PodeEndpoint) for HTTPS (detailed below).
+
+## Server Type
+
+To start using the Pode server type, you just need to set the `-Type` on [`Start-PodeServer`](../../Functions/Core/Start-PodeServer). The following example is a simple HTTP server that will use this server type:
+
+```powershell
+Start-PodeServer -Type Pode {
+
+    Add-PodeEndpoint -Address * -Port 8090 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Kenobi = 'Hello, there' }
+    }
+}
+```
+
+## HTTPS
+
+To enable your server to use HTTPS, as well as setting the `-Type` like above, you will also need to supply a certificate on [`Add-PodeEndpoint`](../../Functions/Core/Add-PodeEndpoint). By default, on SSL3 and TLS1.2 connections are allowed - you can change this via the configuration described below.
+
+There are 3 ways to do this:
+
+> The `-Certificate` and `-CertificateThumbprint` parameters are not supported.
+> On *nix platforms, only the latter two options are supported.
+
+1. Supplying just the `-CertificateFile`, such as a `.cer`.
+2. Supplying both the `-CertificateFile` and `-CertificatePassword`, such as for `.pfx`.
+3. Supply a `-RawCertificate` of type `X509Certificate`.
+
+The following example is like above, but this time we'll supply some `.pfx` to enable HTTPS support:
+
+```powershell
+Start-PodeServer -Type Pode {
+
+    Add-PodeEndpoint -Address * -Port 8090 -Protocol Https -CertificateFile './cert.pfx' -CertificatePassword 'Hunter2'
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Kenobi = 'Hello, there' }
+    }
+}
+```
+
+### Issues
+
+For HTTPS, there are a few issues you may run into. 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`
+
+## Configuration
+
+There are currently two settings you can define via your `server.psd1` configuration file. Both of these are done within the `Server` section.
+
+### Receive Timeout
+
+The default receive timeout is 100ms, but you can change this to any value above 0:
+
+```powershell
+@{
+    Server = @{
+        Pode = @{
+            ReceiveTimeout = 500
+        }
+    }
+}
+```
+
+### SSL Protocols
+
+The default allowed SSL protocols are SSL3 and TLS1.2, but you can change these to any of: SSL2, SSL3, TLS, TLS11, TLS12, TLS13:
+
+```powershell
+@{
+    Server = @{
+        Pode = @{
+            Ssl= @{
+                Protocols = @('TLS', 'TLS11', 'TLS12')
+            }
+        }
+    }
+}
+```
+
+## Any Problems?
+
+As quite obviously stated, this is experimental. If there are any issues please feel free to [raise them here](https://github.com/Badgerati/Pode/issues).
diff --git a/docs/index.md b/docs/index.md
@@ -17,7 +17,7 @@ Pode is a Cross-Platform framework, *completely written in PowerShell*, to creat
 * Docker support, including images for ARM/Raspberry Pi
 * Azure Functions and AWS Lambda support
 * Listen on a single or multiple IP address/hostnames
-* Support for HTTP, HTTPS, TCP and SMTP
+* Support for HTTP, HTTPS, TCP and SMTP (Experimental cross-platform support for HTTPS)
 * Host REST APIs, Web Pages, and Static Content (with caching)
 * Support for custom error pages
 * Multi-thread support for incoming requests

diff --git a/packers/choco/pode.nuspec b/packers/choco/pode.nuspec
@@ -17,7 +17,7 @@ Pode is a Cross-Platform framework, completely written in PowerShell, for creati
 * Docker support, including images for ARM/Raspberry Pi
 * Azure Functions and AWS Lambda support
 * Listen on a single or multiple IP address/hostnames
-* Support for HTTP, HTTPS, TCP and SMTP
+* Support for HTTP, HTTPS, TCP and SMTP (Experimental cross-platform support for HTTPS)
 * Host REST APIs, Web Pages, and Static Content (with caching)
 * Support for custom error pages
 * Multi-thread support for incoming requests

diff --git a/src/Private/Context.ps1 b/src/Private/Context.ps1
@@ -326,13 +326,13 @@ function Set-PodeServerConfiguration
         Types = @{}
     }
 
-    # sockets
-    if (!(Test-IsEmpty $Configuration.Sockets.Ssl.Protocols)) {
-        $Context.Server.Sockets.Ssl.Protocols = (ConvertTo-PodeSslProtocols -Protocols $Configuration.Sockets.Ssl.Protocols)
+    # sockets (pode)
+    if (!(Test-IsEmpty $Configuration.Pode.Ssl.Protocols)) {
+        $Context.Server.Sockets.Ssl.Protocols = (ConvertTo-PodeSslProtocols -Protocols $Configuration.Pode.Ssl.Protocols)
     }
 
-    if ([int]$Configuration.Sockets.ReceiveTimeout -gt 0) {
-        $Context.Server.Sockets.ReceiveTimeout = (Protect-PodeValue -Value $Configuration.Sockets.ReceiveTimeout $Context.Server.Sockets.ReceiveTimeout)
+    if ([int]$Configuration.Pode.ReceiveTimeout -gt 0) {
+        $Context.Server.Sockets.ReceiveTimeout = (Protect-PodeValue -Value $Configuration.Pode.ReceiveTimeout $Context.Server.Sockets.ReceiveTimeout)
     }
 }