Beginner

// Program.fs - minimal Giraffe application showing the HttpHandler type
open Microsoft.AspNetCore.Builder         // => Provides WebApplication, IApplicationBuilder
open Microsoft.AspNetCore.Hosting         // => Provides IWebHostEnvironment
open Microsoft.Extensions.DependencyInjection // => Provides IServiceCollection
open Giraffe                               // => Core Giraffe namespace

// HttpHandler type alias (from Giraffe source):
// type HttpFunc   = HttpContext -> Task<HttpContext option>
// type HttpHandler = HttpFunc -> HttpContext -> Task<HttpContext option>
// => A handler receives the NEXT function and the current context
// => Returns Some(ctx) to pass control to next handler
// => Returns None to short-circuit the pipeline (request handled)

// The simplest possible HttpHandler: always returns "Hello, Giraffe!"
let helloHandler : HttpHandler =          // => Type annotation is optional (inferred)
    fun (next : HttpFunc) (ctx : HttpContext) ->
        // => next: the next handler in the pipeline
        // => ctx: current request/response context (mutable ASP.NET Core HttpContext)
        task {
            // => task {} is a computation expression for Task<T>
            // => Equivalent to async/await in C#
            ctx.Response.ContentType <- "text/plain"  // => Sets Content-Type header
            do! ctx.Response.WriteAsync("Hello, Giraffe!")  // => Writes response body
            // => do! awaits a Task/Async without binding result
            return! next ctx               // => Passes control to next handler
            // => return! tail-calls next, enabling pipeline continuation
        }

// Wire up: ASP.NET Core builder pattern
let builder = WebApplication.CreateBuilder()    // => Creates host with default config
builder.Services.AddGiraffe() |> ignore         // => Registers Giraffe services with DI
// => |> ignore discards the IServiceCollection return value
// => AddGiraffe() is required for serialization and response negotiation

let app = builder.Build()                       // => Builds the IApplicationBuilder
app.UseGiraffe(helloHandler)                    // => Registers helloHandler as terminal middleware
// => UseGiraffe calls app.Run internally - Giraffe is the last middleware
app.Run()                                       // => Starts Kestrel, blocks until shutdown
// => GET / => "Hello, Giraffe!" (text/plain, 200 OK)

// Minimal Giraffe app returning different text responses
open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// text: string -> HttpHandler
// => Writes a plain text response with Content-Type: text/plain; charset=utf-8
// => Does NOT terminate the pipeline - passes to next after writing
let greetHandler : HttpHandler =
    text "Hello, World!"
    // => Equivalent to:
    // fun next ctx ->
    //   task {
    //     ctx.SetContentType("text/plain; charset=utf-8")
    //     do! ctx.WriteTextAsync("Hello, World!")
    //     return! next ctx
    //   }

// setStatusCode: int -> HttpHandler
// => Sets the HTTP status code on the response
// => Must be combined with a body-writing handler
let notFoundHandler : HttpHandler =
    setStatusCode 404 >=> text "Not Found"
    // => >=> (fish operator) chains two handlers sequentially
    // => First sets status to 404, then writes "Not Found"

// Combining status + text is the standard pattern
let createdHandler : HttpHandler =
    setStatusCode 201 >=> text "Resource created"
    // => 201 Created with a plain text body

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(greetHandler)    // => GET / => "Hello, World!" (200 OK)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Define a record type for the response body
// F# records are immutable by default, perfect for response DTOs
type HealthStatus = {
    Status  : string     // => "ok" | "degraded" | "unhealthy"
    Version : string     // => Application version string
    Uptime  : int64      // => Seconds since startup (int64 for large values)
}
// => Record fields are automatically serialized by System.Text.Json
// => Field names become camelCase in JSON by default with Giraffe

// Create an instance with record literal syntax
let healthResponse = {
    Status  = "ok"       // => Initializes Status field
    Version = "1.0.0"    // => Initializes Version field
    Uptime  = 3600L      // => L suffix means int64 literal
}
// => healthResponse : HealthStatus = { Status = "ok"; Version = "1.0.0"; Uptime = 3600L }

// json: 'T -> HttpHandler
// => Serializes 'T to JSON and writes it to the response
// => Sets Content-Type: application/json; charset=utf-8
let healthHandler : HttpHandler =
    json healthResponse
    // => Response body: {"status":"ok","version":"1.0.0","uptime":3600}
    // => Giraffe uses camelCase serialization by default

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore

let app = builder.Build()
app.UseGiraffe(healthHandler)
// => GET / => {"status":"ok","version":"1.0.0","uptime":3600} (200 application/json)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// route: string -> HttpHandler
// => Matches when the request path equals the given string exactly
// => Case-insensitive by default
// => Returns None if the path does not match (tries next handler in choose)

type HealthDto = { Status: string }     // => Simple DTO for /health endpoint

// choose: HttpHandler list -> HttpHandler
// => Tries each handler in order
// => Returns result of first handler that returns Some ctx
// => Returns None if all handlers return None (triggers 404 middleware)
let webApp : HttpHandler =
    choose [
        route "/"       >=> text "Welcome to Giraffe!"
        // => Matches GET|POST|... / exactly
        // => >=> chains route match with text response

        route "/health" >=> json { Status = "ok" }
        // => Matches /health exactly
        // => Returns JSON { "status": "ok" }

        route "/about"  >=> text "Giraffe by-example tutorial"
        // => Matches /about exactly
        // => Routes are tried top-to-bottom; order matters
    ]
// => No match on any route => choose returns None => ASP.NET Core 404 middleware handles it

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET /         => "Welcome to Giraffe!" (200 text/plain)
// => GET /health   => {"status":"ok"} (200 application/json)
// => GET /about    => "Giraffe by-example tutorial" (200 text/plain)
// => GET /unknown  => 404 (from ASP.NET Core default 404 handler)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// HTTP method combinators: HttpHandler -> HttpHandler
// => Each checks ctx.Request.Method and either passes through or returns None
// => GET h  => matches only GET requests, else returns None
// => POST h => matches only POST requests, else returns None

type TodoItem = { Id: int; Title: string; Done: bool }
// => Immutable record for a simple to-do item

let todos = [
    { Id = 1; Title = "Learn Giraffe"; Done = false }
    { Id = 2; Title = "Write F# tests"; Done = false }
]
// => In-memory list for demonstration; real apps use a database

let webApp : HttpHandler =
    choose [
        GET  >=> route "/todos"        >=> json todos
        // => GET /todos => JSON array of TodoItem records
        // => GET wraps the route+json handler, filters to GET only

        POST >=> route "/todos"        >=> text "TODO: create item"
        // => POST /todos => would deserialize body and create item
        // => Demonstrates same path, different method = different handler

        PUT  >=> route "/todos/1"      >=> text "TODO: update item 1"
        // => PUT /todos/1 => would update item with id=1

        DELETE >=> route "/todos/1"    >=> text "TODO: delete item 1"
        // => DELETE /todos/1 => would delete item with id=1

        // Fallback for method not allowed
        route "/todos" >=> setStatusCode 405 >=> text "Method Not Allowed"
        // => Matches /todos with any unhandled method => 405
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET    /todos   => JSON array (200)
// => POST   /todos   => "TODO: create item" (200)
// => PUT    /todos/1 => "TODO: update item 1" (200)
// => DELETE /todos/1 => "TODO: delete item 1" (200)
// => PATCH  /todos   => "Method Not Allowed" (405)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// routef: PrintfFormat<'T,'U,'V,'W,('X -> HttpHandler)> -> ('X -> HttpHandler) -> HttpHandler
// => Uses F# format string to define path pattern and types
// => %i => int,  %s => string,  %O => Guid (requires specific formatter)
// => Extracts typed values and passes them to a handler function

type UserProfile = {
    Id   : int
    Name : string
    Role : string
}

// Handler factory: receives extracted path param and returns HttpHandler
let getUserHandler (userId : int) : HttpHandler =
    // => userId is already an int, no parsing needed
    // => Format string %i guarantees an integer; non-integer paths return None (404)
    let user = { Id = userId; Name = $"User {userId}"; Role = "member" }
    // => $"..." is F# string interpolation
    // => user : UserProfile (record literal)
    json user
    // => Returns JSON representation of the user record

// Handler with multiple path segments
let getPostCommentHandler (postId : int) (commentId : int) : HttpHandler =
    // => Two int parameters extracted from the route pattern
    let response = {| PostId = postId; CommentId = commentId; Text = "A comment" |}
    // => {| ... |} creates an anonymous record (structural type)
    // => Anonymous records serialize cleanly to JSON
    json response

let webApp : HttpHandler =
    choose [
        GET >=> routef "/users/%i" getUserHandler
        // => Matches /users/42 => getUserHandler 42
        // => Matches /users/7  => getUserHandler 7
        // => Does NOT match /users/abc (not an int) => None => 404

        GET >=> routef "/posts/%i/comments/%i" getPostCommentHandler
        // => Matches /posts/5/comments/3 => getPostCommentHandler 5 3
        // => Two segments extracted and passed as curried arguments

        GET >=> routef "/items/%s" (fun name -> text $"Item: {name}")
        // => %s matches any URL segment as a string
        // => Inline lambda avoids defining a separate function
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET /users/42              => {"id":42,"name":"User 42","role":"member"} (200)
// => GET /posts/5/comments/3    => {"postId":5,"commentId":3,"text":"A comment"} (200)
// => GET /items/hello           => "Item: hello" (200)
// => GET /users/abc             => 404 (non-integer fails routef match)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Query string model for pagination
[<CLIMutable>]                              // => Required for model binding with reflection
type PaginationQuery = {
    Page     : int    // => ?page=N (default 1)
    PageSize : int    // => ?pageSize=N (default 20)
    Search   : string // => ?search=term (optional)
}
// => [<CLIMutable>] generates a default constructor needed by ASP.NET Core binders
// => Without it, Giraffe's bindQueryString cannot instantiate the record

// Manual query parameter extraction
let searchHandler : HttpHandler =
    fun next ctx ->
        task {
            // TryGetQueryStringValue: string -> string option
            // => Returns Some "value" if query param exists, None otherwise
            let searchTerm =
                match ctx.TryGetQueryStringValue "q" with
                | Some term -> term          // => ?q=giraffe => "giraffe"
                | None      -> ""            // => no ?q param => empty string

            // GetQueryStringValue: string -> Result<string, string>
            // => Returns Ok "value" or Error "... not found"
            let page =
                match ctx.TryGetQueryStringValue "page" with
                | Some p -> System.Int32.TryParse(p) |> snd  // => parse int or 0
                            |> fun n -> if n > 0 then n else 1 // => default to 1
                | None   -> 1              // => default page

            let response = {|
                SearchTerm = searchTerm    // => anonymous record for response
                Page       = page
                Results    = [| "item1"; "item2" |]  // => placeholder results
            |}
            return! json response next ctx // => serialize and pass to next
        }

// Structured binding: maps all matching query params to a record at once
let pagedHandler : HttpHandler =
    fun next ctx ->
        task {
            // bindQueryString<'T>: HttpFunc -> HttpContext -> Task<HttpContext option>
            // => Binds all query string values to record 'T
            // => Missing optional fields use default values (0 for int, null for string)
            let query = ctx.BindQueryString<PaginationQuery>()
            // => ?page=2&pageSize=10&search=foo
            // => query = { Page = 2; PageSize = 10; Search = "foo" }
            // => ?page=2 only => query = { Page = 2; PageSize = 0; Search = null }

            let effectivePage     = if query.Page > 0 then query.Page else 1
            let effectivePageSize = if query.PageSize > 0 then query.PageSize else 20
            // => Guard defaults since missing fields bind to 0/null

            return! json {| Page = effectivePage; PageSize = effectivePageSize; Search = query.Search |} next ctx
        }

let webApp : HttpHandler =
    choose [
        GET >=> route  "/search" >=> searchHandler
        GET >=> route  "/items"  >=> pagedHandler
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET /search?q=giraffe&page=2   => {"searchTerm":"giraffe","page":2,"results":["item1","item2"]}
// => GET /items?page=3&pageSize=10  => {"page":3,"pageSize":10,"search":null}
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe
open Giraffe.ViewEngine    // => Provides HTML element functions

// Giraffe ViewEngine: HTML as F# values
// => Each HTML element is a function: XmlNode list -> XmlNode
// => Attributes are functions: string -> XmlAttribute
// => Text nodes: str "..." or rawText "..."

// A simple page layout using ViewEngine combinators
let layout (title : string) (content : XmlNode list) : XmlNode =
    // => Returns a complete HTML document
    html [] [                                  // => <html>
        head [] [                              // => <head>
            meta [_charset "utf-8"]            // => <meta charset="utf-8">
            title [] [str title]               // => <title>...</title>
            // => str: string -> XmlNode (text node, HTML-escaped)
            // => rawText: string -> XmlNode (unescaped - use carefully)
        ]
        body [] content                        // => <body>{content}</body>
    ]
// => layout "My Page" [p [] [str "Hello"]]
// => => <html><head>...<title>My Page</title></head><body><p>Hello</p></body></html>

// A view function returning a styled page
let homeView (name : string) : XmlNode =
    layout "Welcome" [
        h1 [] [str $"Hello, {name}!"]          // => <h1>Hello, Alice!</h1>
        p [] [                                  // => <p>
            str "Welcome to "
            strong [] [str "Giraffe"]           // => <strong>Giraffe</strong>
            str " web framework."
        ]                                       // => </p>
        ul [] [                                 // => <ul>
            li [] [str "Type-safe HTML"]        // => <li>Type-safe HTML</li>
            li [] [str "No template files"]     // => <li>No template files</li>
            li [] [str "Composable views"]      // => <li>Composable views</li>
        ]
    ]
// => Produces a full HTML page with a greeting

// htmlView: XmlNode -> HttpHandler
// => Renders XmlNode to HTML string and writes to response
// => Sets Content-Type: text/html; charset=utf-8
let homeHandler : HttpHandler =
    fun next ctx ->
        task {
            let name = ctx.TryGetQueryStringValue "name" |> Option.defaultValue "World"
            // => ?name=Alice => "Alice", else "World"
            return! htmlView (homeView name) next ctx
            // => Renders homeView and sends response
        }

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(GET >=> route "/" >=> homeHandler)
// => GET /?name=Alice => <html>...<h1>Hello, Alice!</h1>...</html>
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// redirectTo: bool -> string -> HttpHandler
// => First arg: true = permanent (301), false = temporary (302)
// => Second arg: the redirect URL (absolute or relative)
let legacyRedirectHandler : HttpHandler =
    redirectTo true "/api/v2/items"
    // => Sends 301 Moved Permanently with Location: /api/v2/items
    // => Use true for permanent redirects (canonical URL changes)
    // => Use false for temporary redirects (A/B testing, maintenance)

// setHttpHeader: string -> string -> HttpHandler
// => Adds a response header without writing a body
let cacheControlHandler : HttpHandler =
    setHttpHeader "Cache-Control" "public, max-age=3600"
    // => Adds Cache-Control: public, max-age=3600 to response
    // => Chain with a body-writing handler using >=>

let corsPreflightHandler : HttpHandler =
    setHttpHeader "Access-Control-Allow-Origin"  "*"                      >=>
    setHttpHeader "Access-Control-Allow-Methods" "GET, POST, PUT, DELETE" >=>
    setHttpHeader "Access-Control-Allow-Headers" "Content-Type"           >=>
    setStatusCode 204
    // => Responds to CORS preflight OPTIONS with 204 No Content
    // => Multiple >=> chains multiple header-setting handlers

// setContentType: string -> HttpHandler
// => Overrides the Content-Type header for custom MIME types
let csvHandler : HttpHandler =
    setContentType "text/csv" >=>
    setHttpHeader "Content-Disposition" "attachment; filename=data.csv" >=>
    fun next ctx ->
        task {
            do! ctx.Response.WriteAsync("id,name\n1,Alice\n2,Bob\n")
            return! next ctx
        }
// => Returns a CSV file download

let webApp : HttpHandler =
    choose [
        GET    >=> route "/old-items"  >=> legacyRedirectHandler
        GET    >=> route "/items"      >=> cacheControlHandler >=> text "items list"
        OPTIONS >=> route "/items"     >=> corsPreflightHandler
        GET    >=> route "/export.csv" >=> csvHandler
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET    /old-items   => 301 Location: /api/v2/items
// => GET    /items       => 200 "items list" with Cache-Control header
// => OPTIONS /items      => 204 with CORS headers
// => GET    /export.csv  => 200 text/csv attachment
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

type Product = {
    Id    : int
    Name  : string
    Price : decimal
}
// => F# record with decimal for monetary values
// => Serializes to both JSON and XML cleanly

let product = { Id = 1; Name = "Giraffe Mug"; Price = 19.99m }
// => m suffix creates a decimal literal
// => product : Product = { Id = 1; Name = "Giraffe Mug"; Price = 19.99M }

// negotiate: 'T -> HttpHandler
// => Inspects Accept header and selects JSON or XML serializer
// => Accept: application/json    => {"id":1,"name":"Giraffe Mug","price":19.99}
// => Accept: application/xml     => <Product><Id>1</Id><Name>Giraffe Mug</Name>...</Product>
// => Accept: */* (default)       => JSON (first registered serializer wins)
let productHandler : HttpHandler =
    negotiate product
// => negotiate reads ctx.Request.Headers["Accept"]
// => Matches against registered serializers (JSON via System.Text.Json by default)
// => Returns 406 Not Acceptable if no match found

// negotiateWith: IDictionary<string,obj->Task<byte[]>> -> obj -> HttpHandler
// => Provides explicit content type to serializer mapping
// => Used when you need custom MIME types beyond JSON/XML

let webApp : HttpHandler =
    GET >=> route "/product" >=> productHandler

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
// => AddGiraffe() registers default JSON serializer
// => To add XML: builder.Services.AddGiraffe(); and configure GiraffeOptions

let app = builder.Build()
app.UseGiraffe(webApp)
// => GET /product (Accept: application/json) => JSON product representation
// => GET /product (Accept: application/xml)  => 406 (XML not configured by default)
// => GET /product (no Accept header)         => JSON (default)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

[<CLIMutable>]
type CreateUserRequest = {
    Username : string
    Email    : string
    Password : string
}
// => [<CLIMutable>] required for System.Text.Json deserialization
// => Without it, deserialization fails silently or throws
// => Fields map from camelCase JSON: {"username":"alice","email":"...","password":"..."}

// bindJson<'T>: ('T -> HttpHandler) -> HttpHandler
// => Deserializes request body to 'T
// => Calls continuation with the deserialized value
// => Throws if deserialization fails (use tryBindJson for error handling)
let createUserHandler : HttpHandler =
    fun next ctx ->
        task {
            // bindJsonAsync<'T>: unit -> Task<'T>
            // => Async version of bindJson used in task {} blocks
            let! body = ctx.BindJsonAsync<CreateUserRequest>()
            // => Reads and deserializes request body
            // => body : CreateUserRequest
            // => body.Username = "alice", body.Email = "alice@example.com"

            // Simulate creating user (real app would call a service)
            let response = {|
                Id       = 42                  // => Generated ID
                Username = body.Username       // => Echo the provided username
                Email    = body.Email          // => Echo the provided email
                // => Password intentionally excluded from response
            |}

            return! (setStatusCode 201 >=> json response) next ctx
            // => 201 Created with JSON body of created user
        }

// tryBindJson pattern for explicit error handling
let safeCreateHandler : HttpHandler =
    fun next ctx ->
        task {
            // TryBindJsonAsync returns Result<'T, string>
            match! ctx.TryBindJsonAsync<CreateUserRequest>() with
            | Ok body ->
                // => Successfully deserialized
                // => Validate business rules here
                if body.Username.Length < 3 then
                    return! (setStatusCode 400 >=> text "Username too short") next ctx
                    // => 400 Bad Request for validation failure
                else
                    let response = {| Id = 1; Username = body.Username |}
                    return! (setStatusCode 201 >=> json response) next ctx
            | Error err ->
                // => Deserialization failed (malformed JSON, missing required fields)
                return! (setStatusCode 400 >=> text $"Invalid request: {err}") next ctx
                // => 400 Bad Request with descriptive error message
        }

let webApp : HttpHandler =
    choose [
        POST >=> route "/users"        >=> createUserHandler
        POST >=> route "/users/safe"   >=> safeCreateHandler
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => POST /users body={"username":"alice","email":"a@b.com","password":"secret"}
// =>   => 201 {"id":42,"username":"alice","email":"a@b.com"}
// => POST /users/safe body={"username":"x"}
// =>   => 400 "Username too short"
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe
open Giraffe.ViewEngine

[<CLIMutable>]
type LoginForm = {
    Username : string  // => Maps from form field "Username"
    Password : string  // => Maps from form field "Password"
    Remember : bool    // => Maps from checkbox "Remember" (true/false)
}
// => Form field names are case-sensitive by default
// => Giraffe maps by field name (matches HTML input name attribute)

// Show the login form
let loginView : XmlNode =
    html [] [
        body [] [
            form [_method "post"; _action "/login"] [
                // => _method "post" sets method="post" attribute
                // => _action "/login" sets action="/login" attribute
                input [_type "text";     _name "Username"; _placeholder "Username"]
                // => _name matches LoginForm field name (case-sensitive)
                input [_type "password"; _name "Password"; _placeholder "Password"]
                input [_type "checkbox"; _name "Remember"; _value "true"]
                // => Checkboxes send "true" when checked, nothing when unchecked
                button [_type "submit"] [str "Login"]
            ]
        ]
    ]

// Handle form submission
let loginHandler : HttpHandler =
    fun next ctx ->
        task {
            let! form = ctx.BindFormAsync<LoginForm>()
            // => Reads Content-Type: application/x-www-form-urlencoded
            // => Deserializes form fields to LoginForm record
            // => form.Username = "alice", form.Password = "...", form.Remember = true/false

            // Simulate authentication check
            if form.Username = "admin" && form.Password = "secret" then
                // => Real app would hash and compare password securely
                return! (setStatusCode 302 >=> redirectTo false "/dashboard") next ctx
                // => Redirect to dashboard on success
            else
                return! (setStatusCode 401 >=> htmlView loginView) next ctx
                // => Show login form again on failure with 401
        }

let webApp : HttpHandler =
    choose [
        GET  >=> route "/login" >=> htmlView loginView
        POST >=> route "/login" >=> loginHandler
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET  /login                               => HTML login form (200)
// => POST /login body=Username=admin&Password=secret => 302 redirect to /dashboard
// => POST /login body=Username=bad&Password=bad      => 401 login form again
app.Run()

open Giraffe.ViewEngine

// Attribute functions follow underscore naming conventions:
// _class, _id, _href, _src, _type, _name, _value, _placeholder, _required
// Custom attributes use: _data_* or attr "name" "value"

let styledCard (title : string) (body : string) : XmlNode =
    div [_class "card"; _id $"card-{title}"] [
        // => _class: string -> XmlAttribute => class="card"
        // => _id: string -> XmlAttribute    => id="card-title"

        div [_class "card-header"] [
            h2 [_class "card-title"] [str title]
            // => Nested divs for Bootstrap-like card structure
        ]

        div [_class "card-body"] [
            p [_class "card-text"] [str body]
        ]

        div [_class "card-footer"] [
            a [_href "/more"; _class "btn btn-primary"] [str "Read More"]
            // => _href: string -> XmlAttribute => href="/more"
            // => _class chains multiple CSS classes in one string
        ]
    ]
// => Produces:
// => <div class="card" id="card-Title">
// =>   <div class="card-header"><h2 class="card-title">Title</h2></div>
// =>   <div class="card-body"><p class="card-text">body</p></div>
// =>   <div class="card-footer"><a href="/more" class="btn btn-primary">Read More</a></div>
// => </div>

// Data attributes use _data_ prefix
let interactiveElement : XmlNode =
    button [
        _class      "toggle-btn"
        attr        "data-target" "#menu"     // => data-target="#menu"
        // => attr: string -> string -> XmlAttribute for arbitrary attributes
        _type       "button"
    ] [str "Toggle Menu"]
// => <button class="toggle-btn" data-target="#menu" type="button">Toggle Menu</button>

// Boolean attributes (no value) use flag functions
let requiredInput : XmlNode =
    input [
        _type     "email"
        _name     "email"
        _required            // => required (no value, presence is the flag)
        // => _required : XmlAttribute (value-less boolean attribute)
        _placeholder "Enter email"
        _class    "form-control"
    ]
// => <input type="email" name="email" required placeholder="Enter email" class="form-control">

open Giraffe.ViewEngine

type NavItem = {
    Label  : string
    Href   : string
    Active : bool
}
// => Model for navigation links
// => Active flag controls "active" CSS class

// Generate a list from data using List.map
let renderNavItems (items : NavItem list) : XmlNode list =
    items |> List.map (fun item ->
        // => List.map transforms each NavItem to an XmlNode
        let cssClass =
            if item.Active
            then "nav-link active"   // => Active item gets extra CSS class
            else "nav-link"          // => Inactive items get base class only
        // => if/then/else is an expression in F# - returns a value
        li [_class "nav-item"] [
            a [_href item.Href; _class cssClass] [str item.Label]
            // => Inline conditional for class: if/then/else as expression
        ]
    )
// => Returns XmlNode list (not XmlNode) - suitable as children in a parent element

// Conditional rendering: show/hide elements based on state
let renderUserMenu (isLoggedIn : bool) (username : string option) : XmlNode =
    div [_class "user-menu"] [
        if isLoggedIn then
            // => F# conditional in list context using yield
            match username with
            | Some name ->
                span [_class "username"] [str $"Hello, {name}"]
                // => Rendered only when isLoggedIn = true AND username = Some _
            | None ->
                span [_class "username"] [str "Hello, User"]
            a [_href "/logout"; _class "btn"] [str "Logout"]
        else
            a [_href "/login";    _class "btn"] [str "Login"]
            a [_href "/register"; _class "btn"] [str "Register"]
            // => Two nodes rendered in else branch
    ]
// => XmlNode if expressions work inside list literals (implicit yield)

// Compose everything into a navigation bar
let navbar (items : NavItem list) (isLoggedIn : bool) (username : string option) : XmlNode =
    nav [_class "navbar"] [
        ul [_class "nav-list"] (renderNavItems items)
        // => renderNavItems returns XmlNode list - spread into children
        renderUserMenu isLoggedIn username
        // => Another node added after the list
    ]

open Microsoft.AspNetCore.Builder
open Microsoft.AspNetCore.StaticFiles     // => Provides StaticFileOptions
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Static file middleware in ASP.NET Core serves files from wwwroot/
// Project structure:
//   wwwroot/
//     index.html      => GET /index.html
//     css/app.css     => GET /css/app.css
//     js/app.js       => GET /js/app.js
//     images/logo.png => GET /images/logo.png

let webApp : HttpHandler =
    choose [
        GET >=> route "/api/status" >=> json {| Status = "ok" |}
        // => API routes handled by Giraffe
        // => If no route matches, falls through to static files, then 404
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()

// UseStaticFiles MUST be registered BEFORE UseGiraffe
// => Static file middleware short-circuits for matching files
// => If no file found, request passes to Giraffe
app.UseStaticFiles() |> ignore
// => Serves files from wwwroot/ at their natural paths
// => GET /css/app.css => reads wwwroot/css/app.css

// UseDefaultFiles redirects / to index.html
app.UseDefaultFiles() |> ignore
// => GET / => serves wwwroot/index.html if it exists

app.UseGiraffe(webApp)
// => GET /api/status => handled by Giraffe
// => GET /css/app.css => served by static files middleware
// => GET /nonexistent => 404 from ASP.NET Core

app.Run()
// => Order matters: DefaultFiles -> StaticFiles -> Giraffe

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Error response DTO - consistent error shape across all endpoints
type ApiError = {
    Code    : string    // => Machine-readable error code
    Message : string    // => Human-readable description
    Field   : string option  // => Optional: which field caused validation error
}
// => Consistent error shape improves API client experience

// Helper to build error responses
let errorResponse statusCode code message field : HttpHandler =
    setStatusCode statusCode >=>
    json { Code = code; Message = message; Field = field }
// => errorResponse 400 "VALIDATION_ERROR" "Email is invalid" (Some "email")
// => => 400 {"code":"VALIDATION_ERROR","message":"Email is invalid","field":"email"}

// Handler using Result type for business logic errors
let createItemHandler : HttpHandler =
    fun next ctx ->
        task {
            // Simulate business logic with Result type
            let validateInput (input : string) : Result<string, string> =
                if input.Length > 0 then Ok input
                else Error "Input cannot be empty"
            // => validateInput: string -> Result<string, string>
            // => Ok "value" on success, Error "message" on failure

            let input = ctx.TryGetQueryStringValue "name" |> Option.defaultValue ""

            match validateInput input with
            | Ok validName ->
                return! json {| Name = validName; Created = true |} next ctx
                // => 200 with created item
            | Error errMsg ->
                return! errorResponse 400 "INVALID_INPUT" errMsg None next ctx
                // => 400 with structured error response
        }

// Global exception handler for unexpected errors
let exceptionHandler (ex : System.Exception) (logger : Microsoft.Extensions.Logging.ILogger) : HttpHandler =
    // => Called by Giraffe's error handling infrastructure
    // => ex: the exception that was thrown
    // => logger: ILogger from DI
    logger.LogError(ex, "Unhandled exception")     // => Log for monitoring
    setStatusCode 500 >=> json {                   // => 500 Internal Server Error
        Code = "INTERNAL_ERROR"
        Message = "An unexpected error occurred"   // => Never expose exception details to clients
        Field = None
    }
// => exceptionHandler is registered via GiraffeOptions.ErrorHandler

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(GET >=> route "/items" >=> createItemHandler)
app.Run()
// => GET /items?name=Widget  => 200 {"name":"Widget","created":true}
// => GET /items              => 400 {"code":"INVALID_INPUT","message":"Input cannot be empty","field":null}

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Logging         // => Provides ILogger, LogLevel
open Giraffe

// Structured logging uses message templates with named parameters
// => Parameters are captured as structured data, not just string interpolation
// => Enables log aggregation tools (Seq, Application Insights) to query by field

let requestLoggingHandler : HttpHandler =
    fun next ctx ->
        task {
            // GetService<'T>: unit -> 'T
            // => Resolves a service from the DI container
            // => ILogger is registered automatically by ASP.NET Core hosting
            let logger = ctx.GetService<ILogger<obj>>()
            // => ILogger<obj> works for non-class contexts; use a meaningful type in production

            // Structured log with named parameters
            logger.LogInformation(
                "Handling {Method} {Path} from {RemoteIP}",
                ctx.Request.Method,                       // => "GET"
                ctx.Request.Path.Value,                   // => "/api/items"
                ctx.Connection.RemoteIpAddress            // => "127.0.0.1"
            )
            // => Log entry: Handling GET /api/items from 127.0.0.1
            // => Structured: { Method="GET", Path="/api/items", RemoteIP="127.0.0.1" }

            let startTime = System.Diagnostics.Stopwatch.GetTimestamp()
            // => Capture timestamp before next handler runs

            let! result = next ctx        // => Await the rest of the pipeline
            // => After next returns, we know the response status

            let elapsed = System.Diagnostics.Stopwatch.GetElapsedTime(startTime)
            // => Calculate elapsed time since startTime
            logger.LogInformation(
                "Completed {Method} {Path} in {ElapsedMs}ms with {StatusCode}",
                ctx.Request.Method,
                ctx.Request.Path.Value,
                elapsed.TotalMilliseconds,     // => Elapsed in milliseconds (float)
                ctx.Response.StatusCode        // => HTTP status code (int)
            )

            return result    // => Pass result back up the pipeline
        }

// Use log levels appropriately
let loggingLevelsHandler : HttpHandler =
    fun next ctx ->
        task {
            let logger = ctx.GetService<ILogger<obj>>()

            logger.LogDebug("Debug: detailed tracing, disabled in production")
            // => Only emitted when minimum level is Debug or lower
            logger.LogInformation("Info: normal operational events")
            // => Emitted in production at Information level
            logger.LogWarning("Warning: unexpected condition, but not an error")
            // => Emitted at Warning level - worth monitoring
            logger.LogError("Error: operation failed, needs attention")
            // => Emitted at Error level - alerts triggered

            return! text "Logging demonstrated" next ctx
        }

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
builder.Logging.AddConsole() |> ignore   // => Add structured console logging
let app = builder.Build()
app.UseGiraffe(requestLoggingHandler >=> GET >=> route "/test" >=> loggingLevelsHandler)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Problem: handler defined at startup captures values once
// Solution: warbler defers construction to each request

// This WRONG example captures DateTime.UtcNow ONCE at startup:
// let badTimeHandler = text (System.DateTime.UtcNow.ToString())
// => All requests get the same startup timestamp

// warbler: (HttpContext -> HttpHandler) -> HttpHandler
// => Calls the factory function on EVERY request
// => Factory receives the current HttpContext
let goodTimeHandler : HttpHandler =
    warbler (fun ctx ->
        // => This lambda is called on every request
        // => ctx: HttpContext for the current request
        let now = System.DateTime.UtcNow.ToString("u")
        // => DateTime.UtcNow is evaluated fresh for each request
        // => "u" format: "2026-03-19 12:00:00Z" (sortable UTC)
        text $"Current UTC time: {now}"
        // => Returns an HttpHandler (not a Task)
        // => The returned handler is then called with next and ctx
    )
// => Each request gets a fresh timestamp

// warbler reading per-request headers
let featureFlagHandler : HttpHandler =
    warbler (fun ctx ->
        let featureEnabled =
            ctx.Request.Headers.ContainsKey("X-Feature-Beta")
            // => Check if custom header is present
            // => Real app would check a feature flag service
        if featureEnabled then
            text "Beta feature enabled"
        else
            text "Standard feature"
        // => Returns different HttpHandler based on request header
    )

// warbler with DI service resolution
let dynamicHandler : HttpHandler =
    warbler (fun ctx ->
        let config = ctx.GetService<Microsoft.Extensions.Configuration.IConfiguration>()
        // => Resolves IConfiguration from DI on every request
        // => Allows reading hot-reloaded configuration values
        let appMode = config.["AppMode"] |> Option.ofObj |> Option.defaultValue "production"
        text $"App mode: {appMode}"
    )

let webApp : HttpHandler =
    choose [
        GET >=> route "/time"    >=> goodTimeHandler
        GET >=> route "/feature" >=> featureFlagHandler
        GET >=> route "/mode"    >=> dynamicHandler
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
app.Run()
// => GET /time    => "Current UTC time: 2026-03-19 12:00:00Z" (fresh each request)
// => GET /feature => "Beta feature enabled" or "Standard feature"
// => GET /mode    => "App mode: development" (from appsettings.json)

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Configuration   // => IConfiguration, IConfigurationSection
open Giraffe

// appsettings.json structure:
// {
//   "Database": {
//     "ConnectionString": "Server=localhost;Database=mydb;...",
//     "MaxPoolSize": 20
//   },
//   "App": {
//     "Name": "GiraffeApp",
//     "Debug": false
//   }
// }

// Configuration-driven handler using DI injection
let configInfoHandler : HttpHandler =
    fun next ctx ->
        task {
            let config = ctx.GetService<IConfiguration>()
            // => IConfiguration injected from DI
            // => Automatically populated from appsettings.json + environment variables

            // Access nested values with colon-separated paths
            let appName = config.["App:Name"]
            // => Reads "GiraffeApp" from App.Name in JSON
            // => Colon separator for nested keys is the ASP.NET Core convention

            let dbConnStr = config.["Database:ConnectionString"]
            // => Reads connection string; real apps use this for DB initialization
            // => NOT returned in responses - connection strings are sensitive

            let debug =
                config.["App:Debug"]
                |> Option.ofObj
                |> Option.map System.Boolean.Parse
                |> Option.defaultValue false
            // => Parses boolean config value safely
            // => Option.ofObj converts null to None
            // => Option.map parses "true"/"false" strings
            // => Option.defaultValue provides fallback

            return! json {|
                AppName = appName           // => "GiraffeApp"
                DebugMode = debug           // => false
                // => Connection string intentionally excluded
            |} next ctx
        }

// Strong-typed configuration binding (recommended for complex config)
type DatabaseConfig = {
    ConnectionString : string
    MaxPoolSize      : int
}
// => Maps to "Database" section of appsettings.json

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore

// Bind configuration section to a strongly-typed object
let dbConfig = builder.Configuration.GetSection("Database").Get<DatabaseConfig>()
// => dbConfig : DatabaseConfig (or null if section missing)
// => dbConfig.ConnectionString = "Server=localhost;..."
// => dbConfig.MaxPoolSize = 20

// Register as singleton for injection throughout app
if dbConfig <> null then
    builder.Services.AddSingleton(dbConfig) |> ignore
// => Other handlers can now inject DatabaseConfig via DI

let app = builder.Build()
app.UseGiraffe(GET >=> route "/config" >=> configInfoHandler)
app.Run()
// => GET /config => {"appName":"GiraffeApp","debugMode":false}

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Hosting         // => IHostEnvironment
open Giraffe

// Environment-aware handler
let environmentHandler : HttpHandler =
    fun next ctx ->
        task {
            let env = ctx.GetService<IHostEnvironment>()
            // => IHostEnvironment provides EnvironmentName property
            // => Set by ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT env var
            // => Default: "Production"

            // IsDevelopment, IsStaging, IsProduction are extension methods
            let envInfo =
                if env.IsDevelopment() then
                    // => ASPNETCORE_ENVIRONMENT=Development
                    {| Environment = "Development"; VerboseErrors = true; SeedData = true |}
                elif env.IsStaging() then
                    // => ASPNETCORE_ENVIRONMENT=Staging
                    {| Environment = "Staging"; VerboseErrors = false; SeedData = false |}
                else
                    // => Production or any other value
                    {| Environment = "Production"; VerboseErrors = false; SeedData = false |}

            return! json envInfo next ctx
        }

let builder = WebApplication.CreateBuilder()
// => Configuration loading order (later overrides earlier):
// 1. appsettings.json                 - base configuration
// 2. appsettings.Development.json     - development overrides (in dev only)
// 3. appsettings.Production.json      - production overrides (in prod only)
// 4. Environment variables            - override any file value
// 5. Command-line arguments           - highest priority

builder.Services.AddGiraffe() |> ignore
let app = builder.Build()

// Conditional middleware based on environment
if app.Environment.IsDevelopment() then
    app.UseDeveloperExceptionPage() |> ignore
    // => Shows detailed exception page with stack trace in development
    // => NEVER enable in production - exposes internal implementation details
else
    // => In production, use generic error page
    app.UseExceptionHandler("/error") |> ignore
// => UseExceptionHandler catches unhandled exceptions and routes to /error

app.UseGiraffe(GET >=> route "/env" >=> environmentHandler)
app.Run()
// => ASPNETCORE_ENVIRONMENT=Development: {"environment":"Development","verboseErrors":true}
// => ASPNETCORE_ENVIRONMENT=Production:  {"environment":"Production","verboseErrors":false}

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// routeStartsWith: string -> HttpHandler -> HttpHandler
// => Matches requests where path starts with the given prefix
// => Path is NOT stripped - nested handlers see the full path
let v1Routes : HttpHandler =
    routeStartsWith "/api/v1" (
        choose [
            route "/api/v1/users"  >=> text "v1 users"
            route "/api/v1/items"  >=> text "v1 items"
        ]
    )
// => GET /api/v1/users => "v1 users" (full path still visible inside)
// => GET /api/v2/users => None (prefix does not match)

// subRoute: string -> HttpHandler -> HttpHandler
// => Matches prefix AND strips it from the path before passing to nested handlers
// => Nested handlers work with the REMAINING path after the prefix
let v2Routes : HttpHandler =
    subRoute "/api/v2" (
        choose [
            route "/users"  >=> text "v2 users"
            // => Matches /api/v2/users - sees /users after stripping /api/v2
            route "/items"  >=> text "v2 items"
            // => Matches /api/v2/items - sees /items after stripping
            routef "/users/%i" (fun id -> json {| Id = id; Version = "v2" |})
            // => Matches /api/v2/users/42 - sees /users/42 with %i extraction
        ]
    )
// => GET /api/v2/users    => "v2 users"
// => GET /api/v2/users/7  => {"id":7,"version":"v2"}
// => GET /api/v1/users    => None (falls through to v1Routes or 404)

// Practical: organize routes by feature module
let userRoutes : HttpHandler =
    subRoute "/users" (
        choose [
            GET  >=> route ""    >=> text "list users"   // => GET /users
            POST >=> route ""    >=> text "create user"  // => POST /users
            GET  >=> routef "/%i" (fun id -> text $"get user {id}")   // => GET /users/42
            PUT  >=> routef "/%i" (fun id -> text $"update user {id}") // => PUT /users/42
        ]
    )
// => All user routes live together; path /users is defined in ONE place

let webApp : HttpHandler =
    subRoute "/api" (
        choose [
            v1Routes
            v2Routes
            userRoutes
        ]
    )

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// routeCi: string -> HttpHandler
// => Case-insensitive version of route
// => /USERS, /Users, /users all match routeCi "/users"
let caseInsensitiveHandler : HttpHandler =
    choose [
        routeCi "/users" >=> text "users endpoint"
        // => Matches: /users, /Users, /USERS, /uSeRs, etc.

        routeCi "/health" >=> json {| Status = "ok" |}
        // => Matches: /health, /Health, /HEALTH

        routeCiStartsWith "/api" (
            // => routeCiStartsWith: case-insensitive prefix match
            choose [
                routeCi "/api/v1/items" >=> text "api items"
                // => Matches: /API/V1/ITEMS, /api/v1/items, etc.
            ]
        )
    ]

// subRouteCi: case-insensitive subRoute
let apiRoutes : HttpHandler =
    subRouteCi "/api" (
        choose [
            routeCi "/status" >=> text "API is running"
            // => After stripping /api (case-insensitive), matches /status
        ]
    )

// Practical recommendation: use case-insensitive routing for public APIs
// => Clients often use different casing conventions
// => JavaScript/TypeScript URL building may vary case
// => Case-sensitive routing causes hard-to-debug 404s for API consumers

let webApp : HttpHandler =
    choose [
        caseInsensitiveHandler
        apiRoutes
    ]

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
app.Run()
// => GET /USERS   => "users endpoint" (200)
// => GET /Users   => "users endpoint" (200)
// => GET /users   => "users endpoint" (200)
// => GET /API/STATUS => "API is running" (200)

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe
open Giraffe.ViewEngine

type Report = {
    Title  : string
    Total  : int
    Items  : string list
}

let sampleReport = { Title = "Monthly Summary"; Total = 3; Items = ["Alpha"; "Beta"; "Gamma"] }

// Render report as HTML view
let reportHtmlView (report : Report) : XmlNode =
    html [] [
        body [] [
            h1 [] [str report.Title]
            p  [] [str $"Total: {report.Total}"]
            ul [] (report.Items |> List.map (fun item -> li [] [str item]))
        ]
    ]

// Handler that responds based on Accept header
let reportHandler : HttpHandler =
    fun next ctx ->
        task {
            let accept = ctx.Request.Headers["Accept"].ToString()
            // => Accept header value as string
            // => "application/json", "text/html", "*/*", etc.

            if accept.Contains("text/html") then
                // => Client prefers HTML (browser request)
                return! htmlView (reportHtmlView sampleReport) next ctx
                // => Render as HTML document
            elif accept.Contains("text/csv") then
                // => Client prefers CSV (data export)
                let csv =
                    "Title,Count\n" +
                    (sampleReport.Items |> List.map (fun i -> $"{i},1") |> String.concat "\n")
                // => Build CSV string manually
                return! (setContentType "text/csv" >=> text csv) next ctx
                // => Return CSV with proper content type
            else
                // => Default: JSON for API clients or unspecified Accept
                return! json sampleReport next ctx
        }

let webApp : HttpHandler =
    GET >=> route "/report" >=> reportHandler

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => GET /report (Accept: text/html)     => Full HTML page
// => GET /report (Accept: text/csv)      => CSV data
// => GET /report (Accept: *)             => JSON data
app.Run()

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Giraffe

// Request metadata inspection handler
let requestMetaHandler : HttpHandler =
    fun next ctx ->
        task {
            // Access request headers using indexer (returns StringValues)
            let userAgent =
                ctx.Request.Headers["User-Agent"].ToString()
            // => "Mozilla/5.0 ..." or "curl/7.68" etc.
            // => .ToString() converts StringValues to plain string

            let contentType =
                ctx.Request.ContentType
                |> Option.ofObj
                |> Option.defaultValue "not set"
            // => "application/json; charset=utf-8" or null
            // => Option.ofObj: converts null string to None

            let contentLength =
                ctx.Request.ContentLength
                |> Option.ofNullable
                |> Option.map int64
                |> Option.defaultValue 0L
            // => Option.ofNullable: Nullable<int64> -> int64 option
            // => Returns None if no Content-Length header

            // ASP.NET Core request tracing ID
            let traceId = ctx.TraceIdentifier
            // => Unique string per request, useful for log correlation
            // => "0HN7MLNP6VFDN:00000001" format

            // Custom header extraction
            let apiVersion =
                ctx.Request.Headers["X-API-Version"].ToString()
                |> fun v -> if System.String.IsNullOrEmpty(v) then "1" else v
            // => X-API-Version: 2 => "2", missing header => "1"

            return! json {|
                UserAgent     = userAgent
                ContentType   = contentType
                ContentLength = contentLength
                TraceId       = traceId
                ApiVersion    = apiVersion
            |} next ctx
        }

let webApp : HttpHandler =
    POST >=> route "/inspect" >=> requestMetaHandler

let builder = WebApplication.CreateBuilder()
builder.Services.AddGiraffe() |> ignore
let app = builder.Build()
app.UseGiraffe(webApp)
// => POST /inspect (User-Agent: MyClient, X-API-Version: 2)
// =>   => {"userAgent":"MyClient","contentType":"application/json",...,"apiVersion":"2"}
app.Run()