appkit

package
v0.3.0-alpha.2 Latest Latest
Warning

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

Go to latest
Published: Aug 27, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

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

View Source
const DefaultRollbackTimeout = 10 * time.Second

DefaultRollbackTimeout bounds Start's wait for cleanup when application assembly fails after Modules have started.

Variables

View Source
var (
	// ErrContextRequired reports a nil lifecycle context.
	ErrContextRequired = module.ErrContextRequired
	// ErrApplicationUnavailable reports use of a nil, zero, or shutting-down Application.
	ErrApplicationUnavailable = module.ErrApplicationUnavailable
	// ErrIdentitiesUnavailable reports that no identity resolver was installed.
	ErrIdentitiesUnavailable = errors.New("identity resolver is unavailable")
	// ErrPasswordsUnavailable reports that no password authenticator was installed.
	ErrPasswordsUnavailable = errors.New("password authenticator is unavailable")
	// ErrBrowserAuthenticationUnavailable reports that no redirect authenticator was installed.
	ErrBrowserAuthenticationUnavailable = errors.New("browser authenticator is unavailable")
	// ErrSessionsUnavailable reports that no session manager was installed.
	ErrSessionsUnavailable = errors.New("session manager is unavailable")
	// ErrTokensUnavailable reports that no token authenticator was installed.
	ErrTokensUnavailable = errors.New("token authenticator is unavailable")
	// ErrDatabaseUnavailable reports that no business-data Store was installed.
	ErrDatabaseUnavailable = errors.New("database store is unavailable")
	// ErrAuthorizerUnavailable reports that no policy evaluator was installed.
	ErrAuthorizerUnavailable = errors.New("authorizer is unavailable")
	// ErrTaskInspectorUnavailable reports that task inspection was not selected.
	ErrTaskInspectorUnavailable = errors.New("task inspector is unavailable")
	// ErrAuditReaderUnavailable reports that audit inspection was not selected.
	ErrAuditReaderUnavailable = errors.New("audit reader is unavailable")
	// ErrObservabilityUnavailable reports that telemetry was not selected.
	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

func ValidateMetadata(metadata Metadata) error

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) Metadata

func (contract Contract) Metadata() Metadata

Metadata returns the validated application identity.

func (Contract) Modules

func (contract Contract) Modules() []ModuleContract

Modules returns the selected static Module contracts in stable ID order.

func (Contract) Provider

func (contract Contract) Provider(capability module.Capability) (string, bool)

Provider returns the sole selected Module that provides capability.

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

type Runtime = action.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.

Jump to

Keyboard shortcuts

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