Skip to content

examples.md

Latest commit

 

History

History
209 lines (141 loc) · 6.79 KB

examples.md

File metadata and controls

209 lines (141 loc) · 6.79 KB
Raw

Examples Guide

Servekit's examples are a guided tour, not a random pile of demos. Start with the shortest useful service, then see the shared Opskit composition path before moving outward into telemetry, route-level policy, lifecycle, customization, and raw HTTP escape hatches.

If you want the short directory index instead, use Servekit Examples.

The examples/ directory includes a guided index, and the source comments in each example main.go explain the key ideas in place.

Start here

examples/basic

This is the first example to read.

It shows the main Servekit promise in one place:

  • New
  • Handle
  • Run
  • built-in operational endpoints
  • JSON encoding, IDs, access logs, and panic recovery by default
  • built-in OTel middleware that uses application-owned global providers

If this example does not feel compelling, the rest of the package probably will not either.

examples/operations

This is the smallest Kit Series presentation example.

It shows:

  • one application-owned Opskit registry
  • required and informational component registration
  • Opskit-backed /readyz
  • authenticated /admin/components inventory
  • authenticated /admin/components/{name} status and inspection snapshots
  • cached readiness state changing without an active check on the probe path

The example imports only Servekit and Opskit. Domain kits join this surface by implementing Opskit contracts and being registered by the application; Servekit never needs to know which package produced a component.

examples/kit-series-composition

This is the canonical single-service composition for the currently available kits.

It shows:

  • typed Configkit state registered with Opskit
  • cached Dependkit readiness refreshed by a Workerkit check-group loop
  • Workerkit runtime state registered with the same Opskit registry
  • Servekit /readyz and authenticated /admin/components presentation
  • one small application route reading current typed configuration
  • explicit Workerkit startup and shutdown around the Servekit server
  • active Workerkit HTTP controls intentionally left to focused Workerkit examples

The example has its own nested Go module so the sibling kits do not appear in Servekit's published module graph. Its local replace directive builds against the checked-out Servekit source, and repository verification tests both modules.

examples/telemetry

Shows the stronger telemetry story directly:

  • global tracer and meter providers
  • process-wide stdout exporters used only by this example
  • request spans through Servekit's default OTel middleware
  • request metrics through Servekit's default OTel middleware
  • server connection metrics on the Run(...) path

Read this when you want proof that Servekit's telemetry story is real, not just configurable.

examples/endpoint-controls

Shows the custom-middleware and route-level policy story:

  • WithMiddleware(...)
  • WithAuthCheck(...)
  • WithAuthGate(...)
  • WithEndpointMiddleware(...)
  • WithBodyLimit(...)
  • WithEndpointTimeout(...)
  • route-local observability suppression

Read this when a service mostly wants the default server but needs a little application-owned global policy and a few routes with different local behavior.

Build outward from the core path

examples/custom-encoding

Shows how a service can keep the Servekit model while enforcing a custom response contract:

  • global success encoder override
  • global error encoder override
  • per-endpoint success encoder override
  • HTTPError-based status control

examples/readiness

Shows the standalone lifecycle story for a small service without Opskit:

  • a lightweight readiness predicate over local state
  • explicit warmup behavior
  • custom /healthz
  • shutdown drain delay

examples/logging

Shows the logging story:

  • custom slog logger
  • explicit http.Server.ErrorLog
  • request ID access from context
  • panic recovery behavior

examples/cors

Shows opt-in browser integration:

  • WithCORSConfig(...)
  • preflight behavior
  • actual CORS response headers
  • credentialed origin allowlists

Advanced integration examples

examples/external-server

Shows how Servekit composes with pre-existing HTTP infrastructure:

  • WithMux(...)
  • Handler()
  • externally owned http.Server
  • explicit SetReady(...)

This is one of the most important advanced examples because it proves Servekit does not have to own the full runtime.

examples/advanced-composition

Shows what a more heavily customized Servekit service can still look like without abandoning the main model:

  • custom success and error encoders
  • custom slog and http.Server.ErrorLog
  • standalone local readiness predicates and explicit readiness control
  • custom /healthz
  • CORS config
  • telemetry provider and labeling overrides
  • global middleware plus route-level overrides
  • one raw HandleHTTP(...) route inside the same service

This is the late-stage reference example to read when you want to see many advanced hooks composed together in one runnable program.

Raw HTTP escape hatches

examples/streaming

Shows why HandleHTTP exists for streaming:

  • server-sent events
  • http.Flusher
  • long-lived response flow

This is the dedicated example to read if you want to see http.Flusher used through Servekit's raw handler path.

examples/reverse-proxy

Shows proxy-style raw handler integration:

  • httputil.ReverseProxy
  • request rewriting
  • response rewriting
  • upstream error handling

examples/response-capture

Shows one of the package's subtler implementation details:

  • implicit 200 capture when handlers never call WriteHeader
  • response byte counting for logs and metrics
  • preserved http.Flusher
  • preserved http.Hijacker

This example is less about "how to build an app" and more about "why the raw Servekit path is technically credible." It also contains the concrete http.Hijacker route in the example set.

Running examples

Run ordinary examples directly from the repository root with:

go run ./examples/<name>

# for example
go run ./examples/basic
go run ./examples/operations
go run ./examples/endpoint-controls
go run ./examples/streaming

The telemetry and Kit Series composition examples use isolated modules to keep application-only dependencies out of Servekit's root module graph:

go -C examples/telemetry run .
go -C examples/kit-series-composition run .

Each example prints suggested curl commands on startup.