Documentation
¶
Overview ¶
The admin console's read-only JSON API at /api, ported from 8f2af2e:src/keepsake/server/api.py.
The admin session, ported from 8f2af2e:src/keepsake/server/auth.py: one password, one signed cookie.
Bundle uploads: a gzipped tar of OKF files, read as `keepsake import` reads a directory.
Who a /mcp request acts as. Auth mode none binds one tenant at startup; jwt mode takes the tenant from an HS256 token on every request, so one server serves many tenants.
The MCP wiring, ported from 2de90d2:src/keepsake/server/tools.py's register and 8f2af2e:src/keepsake/server/app.py's streamable HTTP app.
Prometheus metrics, served on their own port so a public Ingress to /mcp never exposes them.
The seven advertised tools, ported from 2de90d2:src/keepsake/server/tools.py's _TOOLS in wire key order.
Static console serving and Starlette's routing quirks.
Index ¶
- Constants
- func AccessLog(next http.Handler) http.Handler
- func AdminPassword() (string, error)
- func FixedTenant(tenant uuid.UUID) func(http.Handler) http.Handler
- func MetricsHandler(stat func() *pgxpool.Stat) http.Handler
- func NewAPI(svc *services.ConsoleService, a *Auth) http.Handler
- func NewMCPHandler(t *services.ConceptService) http.Handler
- func RefuseBrowsers(next http.Handler) http.Handler
- func ReplaceBundle(svc *services.BundleService) http.HandlerFunc
- func SlashRedirect(mux *http.ServeMux, def http.Handler) http.Handler
- func StaticConsole(root fs.FS) http.Handler
- func UIEnabled() bool
- func WriteJSON(w http.ResponseWriter, r *http.Request, status int, v any)
- type Auth
- type JWT
- type MisconfiguredAdmin
Constants ¶
const ( // MaxBodyChars is about 25k tokens: a deliberate large page that still leaves room to work. MaxBodyChars = 100_000 // DefaultListLimit matches MaxLimit, about 8 KB of paths. DefaultListLimit = MaxLimit // MaxListLimit is about 40 KB of paths, the size of one default body page. MaxListLimit = 1000 )
The bounds on what one read or list accepts; services holds the bounds on what it returns.
const Actor = "keepsake/" + Version
Actor is the revision log's actor in auth mode none, where a request carries no caller identity.
const MaxLimit = 200
MaxLimit caps and advertises a call's results, so one call cannot return the whole corpus.
const MaxVersion = 1<<53 - 1
MaxVersion is the largest integer a JSON number carries exactly, far below bigint's maximum.
const Version = "0.8.0"
Version is this release. scripts/release.sh sets it to Chart.yaml's appVersion.
Variables ¶
This section is empty.
Functions ¶
func AccessLog ¶ added in v0.8.0
AccessLog logs one line per request: at debug when it succeeds, so probes stay quiet, and at warn from 400 up. It logs the route pattern, never the path, since a path names a concept.
func AdminPassword ¶
AdminPassword reads KEEPSAKE_ADMIN_PASSWORD, refusing when the console is on without one.
func FixedTenant ¶
FixedTenant serves every request as tenant, for auth mode none.
func NewAPI ¶
func NewAPI(svc *services.ConsoleService, a *Auth) http.Handler
NewAPI serves the admin API. Mount it at /api with the prefix stripped.
func NewMCPHandler ¶
func NewMCPHandler(t *services.ConceptService) http.Handler
NewMCPHandler serves the seven keepsake tools over stateless streamable HTTP with JSON responses.
func RefuseBrowsers ¶
RefuseBrowsers answers Starlette's bare 403 to a /mcp or /bundle request with an Origin, which only a browser sends.
func ReplaceBundle ¶
func ReplaceBundle(svc *services.BundleService) http.HandlerFunc
ReplaceBundle answers PUT /bundle?prefix=P: the caller's concepts under P become exactly the uploaded bundle.
func SlashRedirect ¶
SlashRedirect 307s an unmatched path to its slash-toggled twin if that has a route, as Starlette does.
func StaticConsole ¶
StaticConsole serves the console as StaticFiles(html=True) does, with index.html for any missing file.
Types ¶
type Auth ¶
type Auth struct {
// contains filtered or unexported fields
}
Auth is the one admin account. The password is the whole credential.
func NewAuth ¶
NewAuth derives the cookie key from the password with scrypt, so a password change revokes every cookie.
func (*Auth) CheckPassword ¶
type JWT ¶
JWT verifies HS256 tokens from one trusted issuer. Secrets[0] signs; every secret verifies, for rotation.
func JWTFromEnv ¶
JWTFromEnv reads KEEPSAKE_JWT_ISSUER, KEEPSAKE_JWT_AUDIENCE and one secret per line of KEEPSAKE_JWT_SECRET_FILE.
func (*JWT) Middleware ¶
Middleware binds the verified caller, or answers 401 for a bad token and 403 for a token naming no tenant.
type MisconfiguredAdmin ¶
type MisconfiguredAdmin struct{ Msg string }
MisconfiguredAdmin is returned at startup. An enabled console with no password is worse than none.
func (*MisconfiguredAdmin) Error ¶
func (e *MisconfiguredAdmin) Error() string