chi

func Handler ¶

func Handler[Req, Resp any](handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp], opts Options) http.HandlerFunc

Handler wraps a rest.RouteHandle and a HandlerFunc into an http.HandlerFunc suitable for use with a chi.Router.

func HandlerLatest ¶ added in v0.11.0

func HandlerLatest[Req, Resp any](
	handle *rest.RouteHandle[Req, Resp],
	src gstream.Stream[Resp],
	opts Options,
) http.HandlerFunc

HandlerLatest returns an http.HandlerFunc that responds to every request with the most recently emitted value from src.

A background goroutine reads src.Values and atomically stores each value. On the first request before any value is available, the handler calls opts.ErrorHandler with HTTP 503 and NoLatestValueError. Errors from src.Errors are silently dropped — latest value is unaffected.

Codec coverage — all HTTP layers validated ¶

Handler validates all codec layers before fn fires: body codec, query params, cookie params, header params, path params, and security. Decoded Req and all param values are validated but not used — response is always from src. Invalid requests produce the standard 400; only well-formed requests get the cached value.

func IngestAdapter ¶ added in v0.11.0

func IngestAdapter[T any](
	r gochi.Router,
	handle *rest.RouteHandle[T, struct{}],
	opts IngestAdapterOptions,
) ports.SourceAdapter[T]

IngestAdapter returns a ports.SourceAdapter that accepts HTTP requests as pipeline items via a chi router. When Activate is called it registers a handler on r and runs until ctx is cancelled. Use with ports.SourcePort.Bind:

domain.SensorReadings.Bind(ctx, chi.IngestAdapter(
    r, ingestHandle, chi.IngestAdapterOptions{Buffer: 8}))

func PipelineAdapter ¶ added in v0.11.0

func PipelineAdapter[Req, Resp any](
	r gochi.Router,
	handle *rest.RouteHandle[Req, Resp],
	opts PipelineAdapterOptions,
) ports.ToolAdapter[Req, Resp]

PipelineAdapter returns a ports.ToolAdapter that registers the pipeline function as an HTTP endpoint via PipelineHandler on a chi router. When ports.ToolPort.Bind is called it registers the handler. Use with ports.ToolPort.Bind:

domain.OEEToolPort.Bind(ctx, chi.PipelineAdapter(r, httpHandle, chi.PipelineAdapterOptions{}))

func PipelineHandler ¶ added in v0.11.0

func PipelineHandler[Req, Resp any](
	handle *rest.RouteHandle[Req, Resp],
	fn PipelineHandlerFunc[Req, Resp],
	opts Options,
) http.HandlerFunc

PipelineHandler wraps a PipelineHandlerFunc into an http.HandlerFunc. All codec validation, param validation, security enforcement, and observer integration follow the same path as plain Handler.

Use PipelineHandler when the handler body benefits from gstream.Tap for declarative intermediate observation, multi-step gstream.Apply, or gstream.MapErr for per-step typed error recovery.

Codec coverage — all HTTP layers ¶

Before fn is called, Handler validates body codec, all param codecs (query, cookie, header, path), and security. After fn returns, Handler validates response body, response header, and response cookie codecs.

To access path/query/cookie/header param VALUES inside the pipeline, call RequestFromContext on the ctx passed to fn (params are already validated):

chi.RegisterPipeline(r, handle,
    func(ctx context.Context, body SensorBody) stream.Stream[OEEResult] {
        sensorID := gochi.URLParam(chi.MustGetRouteContext(ctx), "sensorID")
        s := stream.Single(ctx, body)
        return stream.Tap(ctx, s, func(v SensorBody) {
            slog.Info("request", "sensor", sensorID)
        })
    }, opts)

func Register ¶

func Register[Req, Resp any](r gochi.Router, handle *rest.RouteHandle[Req, Resp], fn HandlerFunc[Req, Resp], opts Options)

Register registers the route on r using its method and path from the route descriptor. Chi uses the same {param} placeholder syntax as go-codex path templates, so no translation is needed.

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	gochi "github.com/go-chi/chi/v5"

	chiadapter "github.com/DaniDeer/go-codex/adapters/chi"
	"github.com/DaniDeer/go-codex/api/rest"
	"github.com/DaniDeer/go-codex/codex"
)

func main() {
	type CreateReq struct{ Name string }
	type Item struct{ ID, Name string }

	reqCodec := codex.Struct[CreateReq](
		codex.RequiredField("name", codex.String(),
			func(r CreateReq) string { return r.Name },
			func(r *CreateReq, v string) { r.Name = v },
		),
	)
	itemCodec := codex.Struct[Item](
		codex.RequiredField("id", codex.String(),
			func(i Item) string { return i.ID },
			func(i *Item, v string) { i.ID = v },
		),
		codex.RequiredField("name", codex.String(),
			func(i Item) string { return i.Name },
			func(i *Item, v string) { i.Name = v },
		),
	)

	b := rest.NewBuilder(rest.Info{Title: "Example API", Version: "1.0.0"})
	handle, err := rest.NewRoute[CreateReq, Item]("POST", "/items",
		reqCodec, itemCodec,
		rest.RouteMeta{OperationID: "createItem", RespStatus: "201"},
	).Register(b)
	if err != nil {
		fmt.Println("register error:", err)
		return
	}

	r := gochi.NewRouter()
	chiadapter.Register(r, handle, func(_ context.Context, req CreateReq) (Item, error) {
		return Item{ID: "1", Name: req.Name}, nil
	}, chiadapter.Options{})

	srv := httptest.NewServer(r)
	defer srv.Close()

	resp, _ := http.Post(srv.URL+"/items", "application/json",
		strings.NewReader(`{"name":"Widget"}`))
	defer resp.Body.Close()
	fmt.Println(resp.StatusCode)
}

Output:
201

func RegisterLatest ¶ added in v0.11.0

func RegisterLatest[Req, Resp any](
	r gochi.Router,
	handle *rest.RouteHandle[Req, Resp],
	src gstream.Stream[Resp],
	opts Options,
)

RegisterLatest wires HandlerLatest onto a chi router. Mirrors Register.

func RegisterPipeline ¶ added in v0.11.0

func RegisterPipeline[Req, Resp any](
	r gochi.Router,
	handle *rest.RouteHandle[Req, Resp],
	fn PipelineHandlerFunc[Req, Resp],
	opts Options,
)

RegisterPipeline wires PipelineHandler onto a chi router. Mirrors Register.

func RegisterSSE ¶

func RegisterSSE[Req, Event any](r gochi.Router, handle *rest.SSERouteHandle[Req, Event], fn SSEHandlerFunc[Req, Event], opts Options)

RegisterSSE wires an rest.SSERouteHandle onto a chi router as a GET SSE endpoint.

func RequestFromContext ¶

func RequestFromContext(ctx context.Context) (*http.Request, bool)

RequestFromContext retrieves the *http.Request stored in ctx by Handler. Returns false if the context was not created by this package.

func ResponseHeadersFromContext ¶

func ResponseHeadersFromContext(ctx context.Context) (http.Header, bool)

ResponseHeadersFromContext retrieves response headers previously stored by WithResponseHeaders. Returns false if no headers were set.

func SSEAdapter ¶ added in v0.11.0

func SSEAdapter[Event any](
	r gochi.Router,
	handle *rest.SSERouteHandle[struct{}, Event],
	opts SSEAdapterOptions,
) ports.SinkAdapter[Event]

SSEAdapter returns a ports.SinkAdapter that serves each SinkPort item as an SSE event to all connected clients via a chi router. When Activate is called it registers an SSEFromHub-backed handler. Use with ports.SinkPort.Bind:

domain.OEEResults.Bind(ctx, chi.SSEAdapter(r, sseHandle, chi.SSEAdapterOptions{}))

func SSEHandler ¶

func SSEHandler[Req, Event any](handle *rest.SSERouteHandle[Req, Event], fn SSEHandlerFunc[Req, Event], opts Options) http.HandlerFunc

SSEHandler wraps an rest.SSERouteHandle and a user-supplied SSEHandlerFunc into an http.HandlerFunc that streams Server-Sent Events.

The handler sets Content-Type: text/event-stream, Cache-Control: no-cache, and Connection: keep-alive, then calls fn. The send func provided to fn validates the event via the codec, encodes it as JSON, writes "data: <json>\n\n" to the response, and flushes. If the event fails validation, send returns an error without writing anything.

fn should honour ctx.Done() for clean client-disconnect handling.

func SetCookie ¶

func SetCookie(w http.ResponseWriter, name, value string, opts CookieOptions) error

SetCookie writes a Set-Cookie header on w with secure defaults: Secure, HttpOnly, SameSite=Strict, Path="/".

If CookieOptions.Codec is non-nil, value is validated first. A validation failure returns rest.CookieParamError without writing any header.

func WithResponseCookies ¶

func WithResponseCookies(ctx context.Context, cookies ...PendingCookie)

WithResponseCookies deposits one or more PendingCookie values into ctx. Handler validates their values against the route's [ResponseCookieParam] codecs and writes Set-Cookie headers on success.

func WithResponseHeaders ¶

func WithResponseHeaders(ctx context.Context, h http.Header)

WithResponseHeaders copies the key-value pairs from h into the response header map stored in ctx (pre-allocated by Handler before calling the HandlerFunc). Call this inside a HandlerFunc to emit response headers such as Location, ETag, or custom headers without direct access to http.ResponseWriter.