Documentation
¶
Overview ¶
Package server exposes mounted OpenVaultDB databases over the minimal HTTP API documented in docs/api.md.
Index ¶
- Variables
- type CORSConfig
- type GrantIdentityConfig
- type Membership
- type MembershipResolver
- type Option
- func WithAccessInstanceID(id string) Option
- func WithAuth(cfg *auth.Config) Option
- func WithCORS(cfg *CORSConfig) Option
- func WithDataDir(dir string) Option
- func WithGrantIdentity(config GrantIdentityConfig) Option
- func WithLogger(logger *slog.Logger) Option
- func WithOwnerAuthorization(authorize OwnerAuthorization) Option
- func WithPrincipalResolver(resolve PrincipalResolver) Option
- func WithPublicOrigin(origin string) Option
- func WithReadOnly(readOnly bool) Option
- type OwnerAuthorization
- type PrincipalResolver
- type Server
Constants ¶
This section is empty.
Variables ¶
var ErrDatabaseMounted = errors.New("database already mounted")
ErrDatabaseMounted is returned by Mount when a database with the same id is already mounted.
var ErrDatabaseNotMounted = errors.New("database not mounted")
ErrDatabaseNotMounted is returned by Unmount for an unknown database id.
Functions ¶
This section is empty.
Types ¶
type CORSConfig ¶
type CORSConfig struct {
// contains filtered or unexported fields
}
CORSConfig holds the allowed-origin set for the CORS middleware. A nil *CORSConfig means CORS is disabled — no headers are added.
func ParseCORSOrigins ¶
func ParseCORSOrigins(values []string) *CORSConfig
ParseCORSOrigins builds a CORSConfig from a list of origin strings. Each element may be:
- "*" — allow any origin (dev only)
- "https://example.com" — exact origin match
- "http://localhost:4200" — exact (scheme + host + port)
Comma-separated values within a single element are split automatically so both --cors "a,b" and --cors a --cors b are equivalent.
func (*CORSConfig) AllowedOrigin ¶
func (c *CORSConfig) AllowedOrigin(origin string) string
AllowedOrigin returns the value to echo back in Access-Control-Allow-Origin, or "" when the origin is not allowed. Exported for testing.
type GrantIdentityConfig ¶ added in v0.4.0
type GrantIdentityConfig struct {
Bootstrap access.PrincipalRef
Resolve MembershipResolver
}
GrantIdentityConfig maps verified bearer grants to typed identities. Bootstrap must come from persistent host configuration. It is never derived from a token, generated on startup, or inferred from a provider subject.
type Membership ¶ added in v0.4.0
Membership is authoritative current state, loaded anew for each request. External OAuth/OIDC bindings remain in the deployment's identity directory.
type MembershipResolver ¶ added in v0.4.0
type MembershipResolver func(context.Context, access.PrincipalRef) (Membership, error)
type Option ¶
type Option func(*Server)
Option configures the Server.
func WithAccessInstanceID ¶ added in v0.5.0
WithAccessInstanceID supplies a stable deployment identity, shared by all mounts on this server. It must come from persistent host configuration.
func WithAuth ¶
WithAuth enables authentication: the connect flow endpoints are served and every data/admin request must carry the owner token or a scoped app token.
func WithCORS ¶
func WithCORS(cfg *CORSConfig) Option
WithCORS configures CORS header injection for browser clients. A nil cfg disables CORS entirely (zero behavior change, the default).
func WithDataDir ¶
WithDataDir enables runtime database creation (POST /v1/databases): each created database gets a manifest YAML plus an inGitDB data directory under dir, so a restart rescan (mount.Dir) remounts them.
func WithGrantIdentity ¶ added in v0.4.0
func WithGrantIdentity(config GrantIdentityConfig) Option
WithGrantIdentity reuses token authentication and capability checks. It adds typed subject/actor propagation and current membership resolution; it does not validate arbitrary external bearer tokens or create an identity store.
func WithLogger ¶ added in v0.6.1
WithLogger sets the logger internal (HTTP 500) errors are reported to. A nil logger keeps the default, slog.Default().
func WithOwnerAuthorization ¶ added in v0.5.0
func WithOwnerAuthorization(authorize OwnerAuthorization) Option
func WithPrincipalResolver ¶ added in v0.4.0
func WithPrincipalResolver(resolve PrincipalResolver) Option
func WithPublicOrigin ¶ added in v0.9.0
WithPublicOrigin sets the externally reachable HTTP(S) origin used in database connection URLs. Callers must validate it before constructing the server. Without it, request scheme and Host are used (suitable for local use).
func WithReadOnly ¶ added in v0.7.0
WithReadOnly makes the entire server read-only. It rejects record, database, and token mutations before authentication or a route handler can cause a side effect. Owner credentials do not bypass this setting.
type OwnerAuthorization ¶ added in v0.5.0
OwnerAuthorization is a trusted deployment binding to each owner's existing authorization authority. A grant at OpenVaultDB never grants administration or protected-row inspection at a lower owner.
type PrincipalResolver ¶ added in v0.4.0
PrincipalResolver maps an authenticated actor to current internal identity and memberships. Implementations are trusted server configuration; callers cannot supply roles, groups, or policy variables in a DTQL request.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves one or more mounted databases.
func (*Server) CloseSnapshots ¶ added in v0.8.0
func (s *Server) CloseSnapshots()
CloseSnapshots removes all materialized query results. Call after stopping HTTP serving and draining in-flight requests during shutdown.
func (*Server) Handler ¶
Handler builds the HTTP handler. Middleware order (outermost first):
- CORS (when --cors is set) — short-circuits preflight OPTIONS before auth
- Auth (when --auth is set) — Layer-1 token validation
- Per-handler capability checks — Layer-2
func (*Server) Mount ¶ added in v0.6.0
Mount starts serving db at runtime. It fails with ErrDatabaseMounted when its id is taken; the server owns db once Mount succeeds.
func (*Server) Unmount ¶ added in v0.6.0
Unmount stops serving database id: new requests get 404 at once, requests already using it run to completion, then the database is closed, releasing its engine resources (e.g. the SQLite file handle). The Close error, if any, is returned; the database is unmounted either way. It waits for in-flight requests without limit; see UnmountContext.
func (*Server) UnmountContext ¶ added in v0.6.0
UnmountContext is Unmount with a bound on the wait for in-flight requests. If ctx ends first, the database stays unrouted, requests in flight keep running, Close runs in the background once they finish (its error is dropped), and ctx.Err() is returned.
Source Files