Files

3.5 KiB

Services and Orchestration - andreaslop-site-hosting

No new domain services or database tables. Orchestration is host composition and one request pipeline.

Host composition (CmsHost)

  • ConfigureServices: AddCmsSecurityHeaders (now with site origin lists), AddCmsWebsite (only when WebsiteMode = PrerenderedPages). Identity registers SetupOptions and ISetupTokenValidator in its own module registration.
  • ConfigurePipeline order (documented in CmsHost):
flowchart TD
    A["Exception handler"] --> B["Security headers"]
    B --> C["Rate limiter"]
    C --> D["HTTPS redirection (no-op on plain HTTP)"]
    D --> E["Admin static mount + /admin redirect"]
    E --> F["Website: compression (non-reserved paths) + noindex"]
    F --> G["Website resolver middleware (pages, assets, redirects, robots)"]
    G --> H["CORS, module middleware, auth"]
    H --> I["MapControllers (/api/v1)"]
    I --> J["Health checks, Sentry tunnel"]
    J --> K["Admin SPA fallback"]
    K --> L["Website 404 (404.html, status 404)"]

    classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef site fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef api fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    class A,B,C,D sec;
    class E,F,G,K,L site;
    class H,I,J api;

Text alternative: security stages first (yellow), then the admin and website mounts (blue), then API routes (green); unknown website paths fall to 404 last, so API 404s are never replaced by the website page.

Notes:

  • The resolver middleware passes reserved prefixes (/admin, /api/v1, /health) straight on, and passes on unknown paths only after API routes had a chance; the final 404 stage serves 404.html with status 404 for non-reserved paths. Pages that resolve (ServeFile, Redirect) are answered in step G, before the API; this is safe because the pure resolver never resolves reserved prefixes.
  • SpaFallback mode keeps today's pipeline untouched.

Request flow (website page)

sequenceDiagram
    box rgba(246,224,94,0.4) Client
        participant B as Browser or proxy Pi
    end
    box rgba(99,179,237,0.4) Host
        participant M as SiteMiddleware
        participant R as PathResolver
        participant F as wwwroot web
    end
    B->>M: GET /Over-Mij?x=1
    M->>R: Resolve path, query, fileExists
    R->>F: fileExists over-mij.html
    F-->>R: true
    R-->>M: Redirect /over-mij?x=1
    M-->>B: 301 Location /over-mij?x=1 plus security headers
    B->>M: GET /over-mij
    M->>R: Resolve
    R-->>M: ServeFile over-mij.html
    M-->>B: 200 html, no-cache, compressed

Text alternative: the middleware asks the pure resolver, which uses a file-exists check; a non-canonical request gets one 301, then the canonical request is served as a file.

Setup flow

Browser loads setup page -> GET /Setup/status -> tokenRequired decides whether the token field is shown -> POST /Setup/owner with X-Setup-Token -> ISetupTokenValidator -> existing ISetupService.CreateInitialOwnerAsync. Login rate limiting policy also covers the setup endpoints (verified in NFR Design).

Build and deploy flow (C6)

CI: admin build per client (env: theme, language, title) -> copy into client wwwroot/admin -> dotnet publish (linux-arm64) -> scp to releases/<id> -> atomic switch of current -> restart user unit -> smoke checks (/health, /api/v1/System/capabilities, a website page). wwwroot/web is a symlink in shared/, so it survives every release.