Documentation
¶
Overview ¶
Package appkit assembles a modular Modary application from consumer-owned Module registrations without exposing lifecycle or execution internals.
Stability: alpha. Until Modary reaches v1, exported Go APIs may change between minor releases. Consumers should pin an exact module version and review release notes before upgrading.
Index ¶
- Constants
- Variables
- func Migrate(ctx context.Context, definition Definition, options Options) error
- func ValidateMetadata(metadata Metadata) error
- type Application
- func (application *Application) AuditReader() (audit.Reader, error)
- func (application *Application) Authorizer() (authz.Authorizer, error)
- func (application *Application) BrowserAuthentication() (identity.BrowserAuthenticator, error)
- func (application *Application) Catalog() []action.CatalogEntry
- func (application *Application) Database() (database.Store, error)
- func (application *Application) Identities() (identity.Resolver, error)
- func (application *Application) Metadata() Metadata
- func (application *Application) Observability() (observe.Service, error)
- func (application *Application) Passwords() (identity.PasswordAuthenticator, error)
- func (application *Application) Ready() bool
- func (application *Application) Runtime() Runtime
- func (application *Application) Sessions() (identity.SessionManager, error)
- func (application *Application) Shutdown(ctx context.Context) error
- func (application *Application) TaskInspector() (task.Inspector, error)
- func (application *Application) Tasks() task.Service
- func (application *Application) Tokens() (identity.TokenAuthenticator, error)
- type Contract
- type Definition
- type DefinitionProvider
- type Metadata
- type ModuleContract
- type Options
- type Runtime
- type RuntimeOptions
Constants ¶
const DefaultRollbackTimeout = 10 * time.Second
DefaultRollbackTimeout bounds Start's wait for cleanup when application assembly fails after Modules have started.
Variables ¶
var ( // ErrContextRequired reports a nil lifecycle context. ErrContextRequired = module.ErrContextRequired ErrApplicationUnavailable = module.ErrApplicationUnavailable ErrIdentitiesUnavailable = errors.New("identity resolver is unavailable") ErrPasswordsUnavailable = errors.New("password authenticator is unavailable") ErrBrowserAuthenticationUnavailable = errors.New("browser authenticator is unavailable") ErrSessionsUnavailable = errors.New("session manager is unavailable") ErrTokensUnavailable = errors.New("token authenticator is unavailable") ErrDatabaseUnavailable = errors.New("database store is unavailable") ErrAuthorizerUnavailable = errors.New("authorizer is unavailable") ErrTaskInspectorUnavailable = errors.New("task inspector is unavailable") ErrAuditReaderUnavailable = errors.New("audit reader is unavailable") ErrObservabilityUnavailable = errors.New("observability is unavailable") )
Functions ¶
func Migrate ¶
func Migrate(ctx context.Context, definition Definition, options Options) error
Migrate validates the complete application graph and applies its selected forward migrations without starting feature Modules or binding handlers.
func ValidateMetadata ¶
ValidateMetadata validates the application identity contract without starting Modules or performing any other side effect.
Types ¶
type Application ¶
type Application struct {
// contains filtered or unexported fields
}
Application is an opaque, fully assembled modular application.
func Start ¶
func Start(ctx context.Context, definition Definition, options Options) (*Application, error)
Start validates the complete static application contract before Module side effects, then starts Modules and assembles the selected component facades.
func (*Application) AuditReader ¶
func (application *Application) AuditReader() (audit.Reader, error)
AuditReader returns selected read-only, scope-bound audit metadata.
func (*Application) Authorizer ¶
func (application *Application) Authorizer() (authz.Authorizer, error)
Authorizer returns the optional lifecycle-gated policy evaluator installed by the consumer's Modules.
func (*Application) BrowserAuthentication ¶
func (application *Application) BrowserAuthentication() (identity.BrowserAuthenticator, error)
BrowserAuthentication returns the selected redirect-based browser authenticator. Local-password-only applications may omit it.
func (*Application) Catalog ¶
func (application *Application) Catalog() []action.CatalogEntry
Catalog returns a defensive copy of the read-only Action catalog.
func (*Application) Database ¶
func (application *Application) Database() (database.Store, error)
Database returns the optional lifecycle-gated business-data Store installed by the consumer's Modules.
func (*Application) Identities ¶
func (application *Application) Identities() (identity.Resolver, error)
Identities returns the optional actor resolver installed by the consumer's Modules.
func (*Application) Metadata ¶
func (application *Application) Metadata() Metadata
Metadata returns the immutable consumer-owned application identity.
func (*Application) Observability ¶
func (application *Application) Observability() (observe.Service, error)
Observability returns the optional bounded telemetry facade.
func (*Application) Passwords ¶
func (application *Application) Passwords() (identity.PasswordAuthenticator, error)
Passwords returns the optional password verifier installed by the consumer's Modules. OIDC-only applications can omit it.
func (*Application) Ready ¶
func (application *Application) Ready() bool
Ready reports whether startup completed and shutdown has not begun.
func (*Application) Runtime ¶
func (application *Application) Runtime() Runtime
Runtime returns the governed Action execution facade, or nil when the application declares no Actions.
func (*Application) Sessions ¶
func (application *Application) Sessions() (identity.SessionManager, error)
Sessions returns the optional session manager installed by the consumer's Modules.
func (*Application) Shutdown ¶
func (application *Application) Shutdown(ctx context.Context) error
Shutdown delegates to the Host-owned exactly-once shutdown sequence and waits within ctx. Host cleanup continues independently if this caller stops waiting.
func (*Application) TaskInspector ¶
func (application *Application) TaskInspector() (task.Inspector, error)
TaskInspector returns selected read-only operational task metadata.
func (*Application) Tasks ¶
func (application *Application) Tasks() task.Service
Tasks returns the optional durable task service installed by the application.
func (*Application) Tokens ¶
func (application *Application) Tokens() (identity.TokenAuthenticator, error)
Tokens returns the optional bearer-token authenticator installed by the consumer's Modules.
type Contract ¶
type Contract struct {
// contains filtered or unexported fields
}
Contract is a pure, validated application snapshot used by transport plans before lifecycle side effects. Its mutable state is private and every returned slice is a defensive copy.
func Preflight ¶
func Preflight(definition Definition, options Options) (Contract, error)
Preflight validates a complete application contract and Runtime policy without invoking Module startup, migration, handler, or shutdown callbacks.
func (Contract) Binds ¶
func (contract Contract) Binds(application *Application) bool
Binds reports whether application was started from the same validated static contract. It does not compare callback identity or inspect dependency values.
func (Contract) Catalog ¶
func (contract Contract) Catalog() []action.CatalogEntry
Catalog returns the validated Action catalog without constructing handlers.
func (Contract) Modules ¶
func (contract Contract) Modules() []ModuleContract
Modules returns the selected static Module contracts in stable ID order.
type Definition ¶
type Definition struct {
Metadata Metadata
Modules []module.Registration
}
Definition is the consumer-owned application composition source. Inspecting it never starts Modules or constructs Action handlers. Start retains Module startup callbacks, handler factories, and migration sources only for its startup attempt; the returned Application does not retain those references. The consumer remains responsible for the lifetime of its original Definition, including any credentials captured by Module startup callbacks.
type DefinitionProvider ¶
type DefinitionProvider func() (Definition, error)
DefinitionProvider constructs a consumer-owned application composition. Invocation is synchronous and has no cancellation context, so providers must perform no runtime startup or unbounded work and must return promptly. Separate commands and project-tool operations may invoke the provider independently.
type Metadata ¶
type Metadata struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
}
Metadata is the consumer-owned identity reported by application transports.
type ModuleContract ¶
type ModuleContract struct {
ID string
Version string
Type module.ModuleType
Requires []module.Capability
Provides []module.Capability
}
ModuleContract is the immutable, callback-free part of one selected Module.
type Options ¶
type Options struct {
Shutdown module.ShutdownPolicy
Runtime RuntimeOptions
// SkipMigrations disables apply-on-start for a serve process paired with an
// explicit Migrate command.
SkipMigrations bool
RollbackTimeout time.Duration
}
Options controls lifecycle and Runtime policy. RollbackTimeout bounds how long Start waits for cleanup after a post-start assembly failure; Host cleanup continues under its own callback policy if that wait expires.
type Runtime ¶
Runtime is the optional governed execution surface exposed by Application. It aliases action.Runtime and provides no Registry or Handler access.
type RuntimeOptions ¶
type RuntimeOptions = action.RuntimePolicy
RuntimeOptions controls Runtime policy without accepting governance dependencies. AppKit resolves those dependencies from the Module Host.