Crate kindling_server 

kindling daemon — HTTP API over a Unix domain socket.

A long-running per-user process that serves the kindling v1 HTTP API, wrapping the in-process kindling_service::KindlingService. This is the kindling serve backend; the CLI wiring lives in a later task (PORT-013). This crate exposes a library surface so it can be both unit/integration tested and driven by the future CLI.

v1 HTTP API

GET    /v1/health                  → 200 { version, schemaVersion, projects: [...] }
POST   /v1/capsules                → 201 Capsule
GET    /v1/capsules/open?sessionId → 200 Capsule | null
PATCH  /v1/capsules/:id/close      → 200 Capsule
POST   /v1/observations            → 201 Observation
POST   /v1/observations/:id/forget  → 204 (redact an observation)
POST   /v1/retrieve                → 200 RetrieveResult
POST   /v1/pins                    → 201 Pin
DELETE /v1/pins/:id                → 204
POST   /v1/context/session-start   → 200 { additionalContext: string | null }
POST   /v1/context/pre-compact     → 200 { additionalContext: string | null }

Request bodies are camelCase JSON; response bodies serialize the domain types (already camelCase). See [dto] for the request shapes. The /v1/context/* endpoints assemble AND format the injected-context markdown server-side (the byte-for-byte date/markdown logic lives in inject).

Per-project routing

Every data endpoint requires the X-Kindling-Project header. Its value is the project root string; the daemon derives the SQLite DB via kindling_store::project_db_path under ServerConfig::kindling_home and caches one service per project. /v1/health needs no header; any other endpoint without it returns 400.

Lifecycle

serve acquires a PID lock (cleaning up a stale file — see [pid]), binds the UDS at mode 0600, builds the router, and runs until idle. The daemon shuts down after ServerConfig::idle_timeout of no in-flight and no recent requests, then removes the socket and PID file.

Modules

inject

Injection-context markdown formatting — the byte-for-byte parity surface.

Structs

AppState

Shared, cloneable application state handed to every handler.

PidGuard

Holds the PID-file lock for the lifetime of the daemon. Removes the file on drop (best-effort).

ServerConfig

Runtime configuration for serve.

Enums

ApiError

Per-request error mapped to an HTTP status + JSON body { "error": "…" }.

ServerError

Top-level daemon error.

Transport

Which transport the daemon binds and serves the v1 HTTP API on.

Constants

DEFAULT_IDLE_TIMEOUT

Default idle timeout before the daemon shuts itself down (30 minutes).

PROJECT_HEADER

Header carrying the project root string for per-project DB routing.

SESSION_HEADER

Header carrying the session id for GET /v1/capsules/open. Accepted as an alternative to the ?sessionId= query param so a hook can resolve a session’s open capsule without a request body (each hook is a fresh process).

Functions

acquire_pid_lock

Acquire the PID-file lock at path, cleaning up a stale file if present.

build_router

Build the v1 API router over the given AppState.

serve

Run the daemon to completion: acquire the PID lock, bind the UDS at mode 0600, serve the v1 API, and shut down on idle — cleaning up the socket and PID file on exit.