gamertan
206d09e4cd
verify / verify (push) Successful in 2m58s
Sanitized snapshot of private source 144ca0a9544042b0477ae732c1356cf0b9d62b3f. Add package selection, adoption workflow, and optional Sandwich Hime integration guidance. AI-Assistance: OpenAI Codex assisted documentation, verification, and publication. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
<!-- SPDX-License-Identifier: MPL-2.0 -->
|
|
|
|
# Getting started
|
|
|
|
Gamertan Web Foundations is adopted one boundary at a time. Start with the
|
|
smallest package that solves a problem the application actually has; do not
|
|
install an imagined framework lifecycle around it.
|
|
|
|
## Choose a first slice
|
|
|
|
| Application need | Begin with | What remains application-owned |
|
|
| --- | --- | --- |
|
|
| Request IDs and trustworthy client addresses | `requestmeta` | Proxy configuration and operational logs |
|
|
| Bounded structured request evidence | `requestmeta`, `requestlog` | Route names, sensitive-field policy, rotation, retention, and access |
|
|
| Browser and HTTP safety primitives | `requestmeta`, `websec` | Exact CSP, route authorization, and response policy |
|
|
| Persistent request-abuse decisions | `requestmeta`, `abuse` | Route classification, storage, appeals, and operator policy |
|
|
| Users, credentials, permissions, and sessions | `auth` | Roles, permissions, login UX, and account policy |
|
|
| Secure browser cookies around `auth` | `authhttp` | Login routes, redirects, pages, and authorization decisions |
|
|
| SQLite persistence for `auth` | `authsqlite` | Database placement, backup, migration approval, and recovery |
|
|
| Aggregate projections over request records | `analytics` | Collection policy, access control, report UI, and retention |
|
|
|
|
The packages are ordinary Go imports. Pin the current preview and verify its
|
|
module checksum:
|
|
|
|
```bash
|
|
go get gamertan.com/web/requestmeta@v0.1.0-preview.1
|
|
go mod verify
|
|
```
|
|
|
|
## Preserve middleware order
|
|
|
|
Packages that consume request metadata must run inside the resolver. Build the
|
|
handler from the application outward; the final resolver assignment becomes
|
|
the first middleware to receive a request:
|
|
|
|
```go
|
|
var handler http.Handler = router
|
|
handler = requestlog.Middleware(sink, logPolicy)(handler)
|
|
handler = websec.Headers(headerPolicy)(handler)
|
|
handler = resolver.Middleware(handler)
|
|
```
|
|
|
|
The complete, copyable composition is in [`starters/basic`](../starters/basic).
|
|
It binds to loopback, shuts down gracefully, and keeps request logging optional.
|
|
|
|
Configure trusted proxy networks narrowly. A forwarding header is not evidence
|
|
by itself; it becomes usable only when the immediate peer and skipped proxy
|
|
hops satisfy the resolver's trust policy. Metadata, authentication, or storage
|
|
failures that affect security decisions should stop the request rather than
|
|
quietly changing identity or policy.
|
|
|
|
## Add HTML without merging responsibilities
|
|
|
|
Handlers should convert request and service state into typed display data.
|
|
They may then render those values with any HTML system. Gamertan's preferred
|
|
companion is [Sandwich Hime](SANDWICH_HIME.md), whose generated components keep
|
|
templates typed while leaving this middleware stack and the `net/http`
|
|
application in control.
|
|
|
|
## Verify the application boundary
|
|
|
|
After adopting a package:
|
|
|
|
```bash
|
|
go mod verify
|
|
go test ./...
|
|
go test -race ./...
|
|
go vet ./...
|
|
go build ./...
|
|
```
|
|
|
|
Test the composed handler with `httptest`, not only the package in isolation.
|
|
Include a normal request, malformed or spoofed metadata, a downstream failure,
|
|
and the application's intended response headers. Existing applications should
|
|
follow the differential and rollback sequence in [ADOPTION.md](ADOPTION.md).
|
|
|
|
Deeper tutorials for accounts, analytics, and persistent abuse policy will be
|
|
written after multiple application migrations have validated those seams. The
|
|
preview documentation describes demonstrated contracts rather than prescribing
|
|
an unfinished application framework.
|