controllers

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 44 Imported by: 0

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

View Source
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.

View Source
const Actor = "keepsake/" + Version

Actor is the revision log's actor in auth mode none, where a request carries no caller identity.

View Source
const MaxLimit = 200

MaxLimit caps and advertises a call's results, so one call cannot return the whole corpus.

View Source
const MaxVersion = 1<<53 - 1

MaxVersion is the largest integer a JSON number carries exactly, far below bigint's maximum.

View Source
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

func AccessLog(next http.Handler) http.Handler

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

func AdminPassword() (string, error)

AdminPassword reads KEEPSAKE_ADMIN_PASSWORD, refusing when the console is on without one.

func FixedTenant

func FixedTenant(tenant uuid.UUID) func(http.Handler) http.Handler

FixedTenant serves every request as tenant, for auth mode none.

func MetricsHandler

func MetricsHandler(stat func() *pgxpool.Stat) http.Handler

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

func RefuseBrowsers(next http.Handler) http.Handler

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

func SlashRedirect(mux *http.ServeMux, def http.Handler) http.Handler

SlashRedirect 307s an unmatched path to its slash-toggled twin if that has a route, as Starlette does.

func StaticConsole

func StaticConsole(root fs.FS) http.Handler

StaticConsole serves the console as StaticFiles(html=True) does, with index.html for any missing file.

func UIEnabled

func UIEnabled() bool

UIEnabled reports whether the admin console is on. It defaults to on.

func WriteJSON

func WriteJSON(w http.ResponseWriter, r *http.Request, status int, v any)

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

func NewAuth(password string) *Auth

NewAuth derives the cookie key from the password with scrypt, so a password change revokes every cookie.

func (*Auth) CheckPassword

func (a *Auth) CheckPassword(supplied string) bool

func (*Auth) Issue

func (a *Auth) Issue(ttl time.Duration) string

Issue returns a cookie of the form "<expiry>.<hexdigest>".

func (*Auth) Valid

func (a *Auth) Valid(cookie string) bool

type JWT

type JWT struct {
	Issuer, Audience string
	Secrets          [][]byte
}

JWT verifies HS256 tokens from one trusted issuer. Secrets[0] signs; every secret verifies, for rotation.

func JWTFromEnv

func JWTFromEnv() (*JWT, error)

JWTFromEnv reads KEEPSAKE_JWT_ISSUER, KEEPSAKE_JWT_AUDIENCE and one secret per line of KEEPSAKE_JWT_SECRET_FILE.

func (*JWT) Middleware

func (j *JWT) Middleware(next http.Handler) http.Handler

Middleware binds the verified caller, or answers 401 for a bad token and 403 for a token naming no tenant.

func (*JWT) Mint

func (j *JWT) Mint(tenant uuid.UUID, sub string, ttl time.Duration, scopes ...string) string

Mint signs a token for tenant, acting as sub, that expires after ttl and carries scopes.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL