Documentation
¶
Overview ¶
Package httpapi provides explicitly mounted HTTP, MCP, health, and static SPA handlers for a Modary application.
Stability: alpha. Until Modary reaches v1, exported Go APIs and Modary-specific wire schemas may change between minor releases. Declared standards versions, including MCPProtocolVersion, retain their normative protocol semantics. Consumers should pin an exact module version and review release notes before upgrading.
Index ¶
- Constants
- func NewAPI(application *appkit.Application, options APIOptions) (http.Handler, error)
- func NewMCP(application *appkit.Application, options MCPOptions) (http.Handler, error)
- func NewSPA(content fs.FS, options SPAOptions) (http.Handler, error)
- type APIOptions
- type MCPOptions
- type SPAOptions
- type ScopeResolver
Constants ¶
const ( // DefaultCookieName is the host-only session cookie used by NewAPI. DefaultCookieName = "modary_session" // DefaultMaxBodyBytes bounds an API request body while leaving room for one // complete Action JSON document and its protocol envelope. DefaultMaxBodyBytes = int64(2 << 20) // MaximumBodyBytes is the largest body limit accepted by NewAPI. MaximumBodyBytes = int64(16 << 20) // DefaultTimeout bounds each API request when no timeout is supplied. DefaultTimeout = 30 * time.Second )
const ( MCPProtocolVersion = "2025-11-25" DefaultMCPMaxBodyBytes int64 = 2 << 20 MaximumMCPBodyBytes int64 = 16 << 20 DefaultMCPRequestTimeout = 30 * time.Second DefaultMCPMaxConcurrentCalls = 32 MaximumMCPConcurrentCalls = 4096 )
MCP protocol and resource limits used when MCPOptions fields are zero.
const ( DefaultSPAIndexFile = "index.html" DefaultSPAIndexCacheControl = "no-cache" DefaultSPAAssetCacheControl = "no-cache" DefaultSPAMaxFiles = 4096 MaximumSPAMaxFiles = 100_000 DefaultSPAMaxFileBytes int64 = 16 << 20 MaximumSPAMaxFileBytes int64 = 64 << 20 DefaultSPAMaxTotalBytes int64 = 64 << 20 MaximumSPAMaxTotalBytes int64 = 512 << 20 )
Static asset defaults keep both bootstrap HTML and consumer-owned assets revalidated unless the consumer explicitly selects a stronger cache policy.
Variables ¶
This section is empty.
Functions ¶
func NewAPI ¶
func NewAPI(application *appkit.Application, options APIOptions) (http.Handler, error)
NewAPI builds the session-authenticated governed Action API. The returned handler owns only /api routes and must be mounted explicitly by the consumer.
func NewMCP ¶
func NewMCP(application *appkit.Application, options MCPOptions) (http.Handler, error)
NewMCP constructs an explicitly mounted, bearer-authenticated MCP endpoint. It implements the non-streaming application/json response profile; GET and DELETE deliberately return 405 because this handler owns no SSE sessions.
Types ¶
type APIOptions ¶
type APIOptions struct {
CookieName string
// EnablePasswordLogin explicitly contributes /api/auth/login. Applications
// using OIDC leave it false and mount the OIDC contribution instead.
EnablePasswordLogin bool
// ResolveScope derives the product execution boundary independently from
// principal identity. It is required for governed Action requests.
ResolveScope ScopeResolver
// AllowInsecureCookie disables the Secure attribute for an explicitly
// HTTP-only development environment. Production applications should retain
// the secure default.
AllowInsecureCookie bool
MaxBodyBytes int64
Timeout time.Duration
}
APIOptions controls the protocol boundary. Zero values select secure, bounded defaults.
type MCPOptions ¶
type MCPOptions struct {
AllowedOrigins []string
MaxBodyBytes int64
RequestTimeout time.Duration
MaxConcurrentCalls int
ResolveScope ScopeResolver
}
MCPOptions configures the stateless JSON response profile of MCP Streamable HTTP. Browser origins are denied unless explicitly allowlisted; non-browser clients normally omit Origin.
type SPAOptions ¶
type SPAOptions struct {
IndexFile string
IndexCacheControl string
AssetCacheControl string
// FallbackExcludedPaths reserves canonical path roots and their descendants
// from index fallback while leaving real static assets addressable.
FallbackExcludedPaths []string
MaxFiles int
MaxFileBytes int64
MaxTotalBytes int64
}
SPAOptions controls the bootstrap document, static-asset cache policy, fallback namespace boundaries, and snapshot limits. Empty fields select the exported defaults.
type ScopeResolver ¶
ScopeResolver derives a validated execution scope for one authenticated request. Implementations should use bounded trusted routing context rather than identity claims that have not been mapped by consumer policy.
Source Files