documentation

pimbrouwers · Dec 13, 2024 · c9fd077 · c9fd077
1 parent ae19e78
commit c9fd077
Show file tree

Hide file tree

Showing 26 changed files with 201 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -7,19 +7,16 @@
 open Falco
 open Falco.Routing
 open Microsoft.AspNetCore.Builder
-// ^-- this import adds many useful extensions
 
 let endpoints =
     [
         get "/" (Response.ofPlainText "Hello World!")
-        // ^-- associate GET / to plain text HttpHandler
     ]
 
 let wapp = WebApplication.Create()
 
 wapp.UseRouting()
     .UseFalco(endpoints)
-    // ^-- activate Falco endpoint source
     .Run()
 ```
 

diff --git a/docs/docs/authentication.html b/docs/docs/authentication.html
@@ -52,9 +52,6 @@ <h3 id="allow-only-authenticated-acces-with-a-certain-scope">Allow only authenti
 </code></pre>
 <h3 id="terminate-authenticated-session">Terminate authenticated session</h3>
 <pre><code class="language-fsharp">open Falco
-</code></pre>
-<h2 id="terminate-authentication">Terminate authentication</h2>
-<pre><code class="language-fsharp">open Falco
 
 let logOut : HttpHandler =
     let authScheme = &quot;...&quot;

diff --git a/docs/docs/cross-site-request-forgery.html b/docs/docs/cross-site-request-forgery.html
@@ -4,10 +4,35 @@
                 gtag('config', 'G-D62HSJHMNZ');</script></head><body class="noto lh-copy"><div class="min-vh-100 mw9 center pa3 overflow-hidden"><nav class="sidebar w-20-l fl-l mb3 mb0-l"><div class="flex items-center"><a href="/docs" class="db w3 w4-l"><img src="/brand.svg" class="br3" /></a><h2 class="dn-l mt3 ml3 fw4 gray">Falco Documentation</h2></div><div class="dn db-l"><h3>Contents</h3><ul class="nl3 f6"><li><a href="get-started.html">Getting Started</a></li><li><a href="routing.html">Routing</a></li><li><a href="response.html">Writing responses</a></li><li><a href="request.html">Accessing request data</a></li><li><a href="markup.html">View engine</a></li><li><a href="cross-site-request-forgery.html">Security</a><ul><li><a href="cross-site-request-forgery.html">Cross Site Request Forgery (XSRF)</a></li><li><a href="authentication.html">Authentication & Authorization</a></li></ul></li><li><a href="example-hello-world.html">Examples</a><ul><li><a href="example-hello-world.html">Hello World</a></li><li><a href="example-hello-world-mvc.html">Hello World MVC</a></li><li><a href="example-dependency-injection.html">Dependency Injection</a></li><li><a href="example-external-view-engine.html">Hello World</a></li><li><a href="example-basic-rest-api.html">Basic REST API</a></li></ul></li><li><a href="migrating-from-v4-to-v5.html">V5 Migration Guide</a></li></ul></div></nav><main class="w-80-l fl-l pl3-l"><h1 id="cross-site-scripting-xss-attacks">Cross-site Scripting (XSS) Attacks</h1>
 <p>Cross-site scripting attacks are extremely common since they are quite simple to carry out. Fortunately, protecting against them is as easy as performing them.</p>
 <p>The <a href="https://docs.microsoft.com/en-us/aspnet/core/security/anti-request-forgery">Microsoft.AspNetCore.Antiforgery</a> package provides the required utilities to easily protect yourself against such attacks.</p>
-<p>Falco provides a few handlers via <code>Falco.Security.Xss</code>:</p>
-<blockquote>
-<p>To use the Xss helpers, ensure that the <code>Antiforgery</code> service has been registered.</p>
-</blockquote>
+<h2 id="activating-antiforgery-protection">Activating Antiforgery Protection</h2>
+<p>To use the Falco Xsrf helpers, ensure that the <code>Antiforgery</code> service has been <a href="https://learn.microsoft.com/en-us/aspnet/core/security/anti-request-forgery">registered</a>.</p>
+<pre><code class="language-fsharp">open Falco
+open Falco.Routing
+open Microsoft.AspNetCore.Builder
+open Microsoft.Extensions.DependencyInjection
+// ^-- this import enables antiforgery activation
+
+let endpoints =
+    [
+        // endpoints...
+    ]
+
+let bldr = WebApplication.CreateBuilder()
+
+bldr.Services
+    .AddAntiforgery()
+
+let wapp = WebApplication.Create()
+
+wapp.UseAntiforgery()
+    // ^-- activate Antiforgery before routing
+    .UseRouting()
+    .UseFalco(endpoints)
+    .Run()
+
+</code></pre>
+<h2 id="falco-xsrf-support">Falco XSRF Support</h2>
+<p>Falco provides a few handlers via <code>Falco.Security.Xsrf</code>:</p>
 <pre><code class="language-fsharp">open Falco.Markup
 open Falco.Security
 

diff --git a/docs/docs/example-basic-rest-api.html b/docs/docs/example-basic-rest-api.html
diff --git a/docs/docs/example-dependency-injection.html b/docs/docs/example-dependency-injection.html
@@ -50,7 +50,8 @@ <h2 id="registering-the-dependency">Registering the Dependency</h2>
                 Response.ofPlainText greeting ctx)
     ]
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 <p>Following through you can see the web server being created in two phases. The first to establish the context (i.e., logging, server configuration and dependencies). Second, freezing the final state and creating a configurable web application.</p>

diff --git a/docs/docs/example-external-view-engine.html b/docs/docs/example-external-view-engine.html
@@ -82,7 +82,6 @@ <h2 id="registering-the-template-engine">Registering the Template Engine</h2>
 open Microsoft.AspNetCore.Builder
 open Microsoft.Extensions.DependencyInjection
 
-
 [&lt;EntryPoint&gt;]
 let main args =
     let bldr = WebApplication.CreateBuilder(args)
@@ -91,12 +90,13 @@ <h2 id="registering-the-template-engine">Registering the Template Engine</h2>
         .AddSingleton&lt;ITemplate, ScribanTemplate&gt;() // &lt;-- register ITemplates implementation as a dependency
         |&gt; ignore
 
-    let wapp = bldr.Build()
-
     let endpoints =
         [ get &quot;/&quot; Pages.homepage ]
 
-    wapp.UseFalco(endpoints)
+    let wapp = bldr.Build()
+
+    wapp.UseRouting()
+        .UseFalco(endpoints)
         .UseFalcoNotFound(Pages.notFound)
         .Run()
 
@@ -105,4 +105,4 @@ <h2 id="registering-the-template-engine">Registering the Template Engine</h2>
 <h2 id="wrapping-up">Wrapping Up</h2>
 <p>Having dabbled with creating HTML applications, now let's set our sights on creating RESTful APIs.</p>
 <p><a href="example-basic-rest-api.html">Next: Example - Basic REST API</a></p>
-</main></div><footer class="cl pa3 bg-merlot"><div class="f7 tc white-70">&copy; 2020-2024 Pim Brouwers & contributors.</div></footer><script src="/prism.js"></script></body></html>
+</main></div><footer class="cl pa3 bg-merlot"><div class="f7 tc white-70">&copy; 2020-2024 Pim Brouwers & contributors.</div></footer><script src="/prism.js"></script></body></html>
diff --git a/docs/docs/example-hello-world-mvc.html b/docs/docs/example-hello-world-mvc.html
@@ -154,8 +154,10 @@ <h2 id="web-server">Web Server</h2>
             .UseFalco(endpoints)
             .UseFalcoNotFound(ErrorPage.notFound)
             .Run()
+
+        0
 </code></pre>
 <h2 id="wrapping-up">Wrapping Up</h2>
 <p>This example was a leap ahead from our basic hello world. But having followed this, you know understand many of the patterns you'll need to know to build end-to-end server applications with Falco. Unsurprisingly, the entire program fits inside 118 LOC. One of the magnificent benefits of writing code in F#.</p>
 <p><a href="example-dependency-injection.html">Next: Example - Dependency Injection</a></p>
-</main></div><footer class="cl pa3 bg-merlot"><div class="f7 tc white-70">&copy; 2020-2024 Pim Brouwers & contributors.</div></footer><script src="/prism.js"></script></body></html>
+</main></div><footer class="cl pa3 bg-merlot"><div class="f7 tc white-70">&copy; 2020-2024 Pim Brouwers & contributors.</div></footer><script src="/prism.js"></script></body></html>
diff --git a/docs/docs/example-hello-world.html b/docs/docs/example-hello-world.html
@@ -10,16 +10,20 @@ <h2 id="creating-the-application-manually">Creating the Application Manually</h2
 <h2 id="code-overview">Code Overview</h2>
 <pre><code class="language-fsharp">open Falco
 open Falco.Routing
-open Microsoft.AspNetCore.Builder // &lt;-- this import adds many useful extensions
-
-let wapp = WebApplication.Create()
+open Microsoft.AspNetCore.Builder
+// ^-- this import adds many useful extensions
 
 let endpoints =
     [
-        get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;) // &lt;-- associate GET / to plain text HttpHandler
+        get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;)
+        // ^-- associate GET / to plain text HttpHandler
     ]
 
-wapp.UseFalco(endpoints) // &lt;-- activate Falco endpoint source
+let wapp = WebApplication.Create()
+
+wapp.UseRouting()
+    .UseFalco(endpoints)
+    // ^-- activate Falco endpoint source
     .Run()
 </code></pre>
 <p>First, we open the required namespaces. <code>Falco</code> bring into scope the ability to activate the library and some other extension methods to make the fluent API more user-friendly.</p>

diff --git a/docs/docs/get-started.html b/docs/docs/get-started.html
@@ -21,14 +21,21 @@ <h2 id="manually-installing">Manually installing</h2>
 </code></pre>
 <p>Remove any <code>*.fs</code> files created automatically, create a new file named <code>Program.fs</code> and set the contents to the following:</p>
 <pre><code class="language-fsharp">open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
-
-let wapp = WebApplication.Create()
+// ^-- this import adds many useful extensions
 
 let endpoints =
-    [ get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;) ]
+    [
+        get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;)
+        // ^-- associate GET / to plain text HttpHandler
+    ]
+
+let wapp = WebApplication.Create()
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
+    // ^-- activate Falco endpoint source
     .Run()
 </code></pre>
 <p>Run the application:</p>

diff --git a/docs/docs/migrating-from-v4-to-v5.html b/docs/docs/migrating-from-v4-to-v5.html
@@ -27,17 +27,22 @@ <h2 id="webhost-expression"><code>webHost</code> expression</h2>
 <td>
 <pre><code class="language-fsharp">// Falco v5.x
 open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
 // ^-- this import adds many useful extensions
 
+let endpoints =
+    [
+        get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;)
+        // ^-- associate GET / to plain text HttpHandler
+    ]
+
 let wapp = WebApplication.Create()
 
-wapp.Use(StaticFileExtensions.UseStaticFiles)
-    .UseFalco([
-        get &quot;/&quot; (Response.ofPlainText &quot;Hello World!&quot;)
-    ])
+wapp.UseRouting()
+    .UseFalco(endpoints)
+    // ^-- activate Falco endpoint source
     .Run()
-
 </code></pre>
 </td>
 </tr>
@@ -65,6 +70,7 @@ <h2 id="configuration-expression"><code>configuration</code> expression</h2>
 </td>
 <td>
 <pre><code class="language-fsharp">open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
 open Microsoft.Extensions.Configuration
 // ^-- this import adds access to Configuration
@@ -79,7 +85,8 @@ <h2 id="configuration-expression"><code>configuration</code> expression</h2>
 
 let endpoints = []
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 </td>
@@ -124,5 +131,5 @@ <h2 id="xss-module-renamed-to-xsrf"><code>Xss</code> module renamed to <code>Xsr
 <h2 id="crypto-module-removed"><code>Crypto</code> module removed</h2>
 <p>The Crypto module provided functionality for: random numbers, salt generation and key derivation. The code in this module was really a veneer on top of the cryptographic providers in the base library. Extracting this code into your project would be dead simple. The <a href="https://github.com/pimbrouwers/Falco/blob/25d828d832c0fde2dfff04775bea1eced9050458/src/Falco/Security.fs#L3">source</a> is permalinked here for such purposes.</p>
 <h2 id="auth-module-removed"><code>Auth</code> module removed</h2>
-<p>The Auth module's functionality was ported to the Response module.</p>
+<p>The <code>Auth</code> module functionality was ported one-to-one to the <code>Response</code> module.</p>
 </main></div><footer class="cl pa3 bg-merlot"><div class="f7 tc white-70">&copy; 2020-2024 Pim Brouwers & contributors.</div></footer><script src="/prism.js"></script></body></html>
diff --git a/docs/docs/request.html b/docs/docs/request.html
@@ -49,15 +49,15 @@ <h2 id="request-data-access">Request Data Access</h2>
 <pre><code class="language-fsharp">let requestData : RequestData = // From: Route | Query | Form
 
 // Retrieve primitive options
-let str : string option = requestData.TryGetString &quot;name&quot; 
+let str : string option = requestData.TryGetString &quot;name&quot;
 let flt : float option = requestData.TryGetFloat &quot;temperature&quot;
 
 // Retrieve primitive, or default
 let str : string = requestData.GetString &quot;name&quot;
 let strOrDefault : string = requestData.GetString (&quot;name&quot;, &quot;John Doe&quot;)
 let flt : float = requestData.GetFloat &quot;temperature&quot;
 
-// Retrieve primitive list 
+// Retrieve primitive list
 let strList : string list = requestData.GetStringList &quot;hobbies&quot;
 let grades : int list = requestData.GetInt32List &quot;grades&quot;
 
@@ -179,9 +179,9 @@ <h2 id="json">JSON</h2>
       LastName : string }
 
 let jsonHandler : HttpHandler =
-    { FirstName = &quot;John&quot;
-      LastName = &quot;Doe&quot; }
-    |&gt; Response.ofJson
+    Response.ofJson {
+        FirstName = &quot;John&quot;
+        LastName = &quot;Doe&quot; }
 
 let mapJsonHandler : HttpHandler =
     let handleOk person : HttpHandler =

diff --git a/docs/docs/routing.html b/docs/docs/routing.html
@@ -8,14 +8,16 @@
 <p>Note: All of the following examples are <em>fully functioning</em> web apps.</p>
 </blockquote>
 <pre><code class="language-fsharp">open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
 
 let wapp = WebApplication.Create()
 
 let endpoints =
     [ get &quot;/&quot; (Response.ofPlainText &quot;hello world&quot;) ]
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 <p>The preceding example includes a single <code>HttpEndpoint</code>:</p>
@@ -30,6 +32,7 @@
 </ul>
 <p>The following example shows a more sophisticated <code>HttpEndpoint</code>:</p>
 <pre><code class="language-fsharp">open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
 
 let wapp = WebApplication.Create()
@@ -43,7 +46,8 @@
             Response.ofPlainText message ctx)
     ]
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 <p>The string <code>/hello/{name:alpha}</code> is a <strong>route template</strong>. It is used to configure how the endpoint is matched. In this case, the template matches:</p>
@@ -62,6 +66,7 @@
 </ul>
 <p>An alternative way to express the <code>HttEndpoint</code> above is seen below.</p>
 <pre><code class="language-fsharp">open Falco
+open Falco.Routing
 open Microsoft.AspNetCore.Builder
 
 let wapp = WebApplication.Create()
@@ -73,7 +78,8 @@
 let endpoints =
     [ mapGet &quot;/hello/{name:alpha}&quot; (fun route -&gt; r.GetString &quot;name&quot;) greetingHandler ]
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 <h2 id="multi-method-endpoints">Multi-method Endpoints</h2>
@@ -99,7 +105,8 @@ <h2 id="multi-method-endpoints">Multi-method Endpoints</h2>
             POST, Response.ofEmpty ]
     ]
 
-wapp.UseFalco(endpoints)
+wapp.UseRouting()
+    .UseFalco(endpoints)
     .Run()
 </code></pre>
 <p><a href="response.html">Next: Writing responses</a></p>