application

package
v1.19.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 53 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MiddlewareGroupHttp = "http"

	/* the pipeline sorts ascending and the first entry becomes the outermost wrapper, so a priority BELOW the default puts the static file server outermost, which is where it is. A request for a file that exists is therefore answered before anything registered through Use observes it: the file server never calls the rest of the chain, so the rate limiter, the compressor and the access log are all skipped for exactly the requests that read files off disk. That is the deliberate trade — the alternative is running the whole application chain for every asset — and an application that needs its own middleware to see static requests registers that middleware below this priority rather than above it. */
	MiddlewarePriorityStatic = -1000
	MiddlewareNameStatic     = "static"

	MiddlewarePriorityDefault = 0
)
View Source 
const ServiceProcessContext = "service.application.process_context"

ServiceProcessContext resolves to the console run's ProcessContext — its generated process id and start moment, the console counterpart of http.ServiceRequestContext. The cli entry point installs it into the run's scope, so it takes a resolver, not the container: the root container never carries it, and an http process carries the request context instead.

View Source 
const ServiceProcessRole = "service.application.process_role"

ServiceProcessRole resolves to the process role string (config.RoleWeb, config.RoleWorker or config.RoleAll) so services can gate background work without reaching back to the application instance.

Variables

This section is empty.

Functions

func NewSignalContext added in v1.17.0 

func NewSignalContext() (context.Context, context.CancelFunc)

NewSignalContext returns a context that is cancelled by the first SIGINT or SIGTERM, giving the application a graceful shutdown window. A second SIGINT or SIGTERM received while that shutdown is still running prints one line to stderr and forces the process to exit with the conventional 128+signal code, so an operator facing a hung shutdown is never reduced to SIGKILL; a second signal landing within half a second of the first is absorbed as a duplicate delivery of the same shutdown request, so a supervisor and a terminal both forwarding one interrupt do not skip the graceful shutdown. The forced exit deliberately runs no teardown: it exists for the shutdown that is already hung, and a teardown on its path could hang the same way — the escalation is the operator's demand for a process that is gone now, at the acknowledged price of whatever a Close would have flushed.

The returned stop function unregisters the signal notifications, cancels the context, and releases the watcher goroutine; it is safe to call more than once and from concurrent goroutines.

func ProcessContextFromResolver added in v1.19.0 

func ProcessContextFromResolver(resolver containercontract.Resolver) applicationcontract.ProcessContext

ProcessContextFromResolver is the error-tolerant form of ProcessContextMustFromResolver, for code that runs on both process shapes and treats the process context as optional: absence — an http process, the root container — answers nil.

func ProcessContextMustFromResolver added in v1.19.0 

func ProcessContextMustFromResolver(resolver containercontract.Resolver) applicationcontract.ProcessContext

func ProcessRoleMustFromContainer added in v1.16.0 

func ProcessRoleMustFromContainer(serviceContainer containercontract.Container) string

func ProcessRoleMustFromResolver added in v1.16.0 

func ProcessRoleMustFromResolver(resolver containercontract.Resolver) string

Types

type Application 

type Application struct {
	// contains filtered or unexported fields
}

func NewApplication 

func NewApplication(
	embeddedEnvFiles fs.FS,
	embeddedPublicFiles fs.FS,
) *Application

func (*Application) Boot 

func (instance *Application) Boot() kernelcontract.Kernel

func (*Application) Close 

func (instance *Application) Close()

func (*Application) MarkParameterSecret added in v1.18.0 

func (instance *Application) MarkParameterSecret(name string)

MarkParameterSecret marks a parameter that already exists — typically one melody registered automatically from the .env artifacts — as holding a credential. A name that matches nothing does not fail the boot, since an environment key is legitimately undefined in some environments; it is retried before the configuration resolves and again at the end of the boot, and warned about only then, so a misspelled name is visible instead of silently redacting nothing.

func (*Application) ProcessRole added in v1.16.0 

func (instance *Application) ProcessRole() string
ProcessRole is the resolved process role (config.RoleWeb, config.RoleWorker or config.RoleAll): an explicit --role flag wins over the MELODY_PROCESS_ROLE parameter, which defaults to all. Melody gates nothing on it — wiring code queries it to decide whether to register background runners (outbox relays, consumers) on this process; services resolve the same value through ServiceProcessRole.

Nothing in this major waits for those runners: when Run returns, the container closes immediately, so a goroutine still draining loses its services under it. A runner that must finish its work observes the run context and completes its drain before the handler that received the context returns.

func (*Application) RegisterCliCommand 

func (instance *Application) RegisterCliCommand(command clicontract.Command)

func (*Application) RegisterConfiguration added in v1.8.0 

func (instance *Application) RegisterConfiguration(name string, configuration any)

func (*Application) RegisterHttpMiddlewareFactories 

func (instance *Application) RegisterHttpMiddlewareFactories(
	factories ...MiddlewareFactory,
)

func (*Application) RegisterHttpMiddlewares 

func (instance *Application) RegisterHttpMiddlewares(middlewares ...httpcontract.Middleware)

func (*Application) RegisterHttpRoute 

func (instance *Application) RegisterHttpRoute(
	method string,
	pattern string,
	handler httpcontract.Handler,
)

RegisterHttpRoute queues one of the application's own routes. The queue drains before any module's RegisterHttpRoutes runs, so where a root route and a module route meet at dispatch, the root route wins the registration-order tie-break: the composition root wrote its route against the application, not against whichever module boots beside it.

func (*Application) RegisterModule 

func (instance *Application) RegisterModule(moduleInstance applicationcontract.Module)

func (*Application) RegisterModuleProvider added in v1.14.0 

func (instance *Application) RegisterModuleProvider(provider applicationcontract.ModuleProvider)

func (*Application) RegisterParameter 

func (instance *Application) RegisterParameter(
	name string,
	value any,
)

func (*Application) RegisterScopedService added in v1.19.0 

func (instance *Application) RegisterScopedService(
	serviceName string,
	provider any,
	options ...containercontract.RegisterOption,
)
RegisterScopedService declares a service the application's scopes own: one instance per scope — one http request, one command run — closed with it. It mirrors RegisterService in everything but lifetime, collisions included — a name claimed at both lifetimes is absorbed into the aggregated boot report, so a module that scopes a name the framework registers later hears about it beside every other collision instead of one panic per boot attempt.

In console the run's scope spans the whole command, so for a one-shot command "scoped" and "per run" are the same thing — but a long-running command that processes many units of work holds one scope for all of them, and a scoped transaction or identity quietly becomes a process singleton. Such a command creates a child runtime per unit, the way the cron runner does around each scheduled run: a fresh scope from Container().NewScope(), a runtime.New over it, and a Close whose error is joined onto the unit's own when the unit ends.

func (*Application) RegisterSecretParameter added in v1.18.0 

func (instance *Application) RegisterSecretParameter(
	name string,
	value any,
)

RegisterSecretParameter declares a parameter holding a credential. It is registered and resolved like any other; the marking only keeps it, and every parameter whose template reads it, out of the rendered configuration.

func (*Application) RegisterService 

func (instance *Application) RegisterService(
	serviceName string,
	provider any,
	options ...containercontract.RegisterOption,
)

func (*Application) Run 

func (instance *Application) Run(ctx context.Context)

type HttpMiddleware 

type HttpMiddleware struct {
	// contains filtered or unexported fields
}

func NewHttpMiddleware 

func NewHttpMiddleware(
	staticOptions *static.Options,
	configuration configcontract.Configuration,
) *HttpMiddleware

func (*HttpMiddleware) LastBuildReport 

func (instance *HttpMiddleware) LastBuildReport() *middlewarepipeline.MiddlewareBuildReport

func (*HttpMiddleware) Use 

func (instance *HttpMiddleware) Use(middlewares ...httpcontract.Middleware)

func (*HttpMiddleware) UseFactories 

func (instance *HttpMiddleware) UseFactories(factories ...MiddlewareFactory)

func (*HttpMiddleware) UseFactoriesWithPriority 

func (instance *HttpMiddleware) UseFactoriesWithPriority(priority int, factories ...MiddlewareFactory)

func (*HttpMiddleware) UseWithPriority 

func (instance *HttpMiddleware) UseWithPriority(priority int, middlewares ...httpcontract.Middleware)

type MiddlewareFactory 

type MiddlewareFactory func(kernelInstance kernelcontract.Kernel) httpcontract.Middleware

type ProcessContext added in v1.19.0 

type ProcessContext struct {
	// contains filtered or unexported fields
}

func NewProcessContext added in v1.19.0 

func NewProcessContext(processId string, startedAt time.Time) *ProcessContext

func (*ProcessContext) ProcessId added in v1.19.0 

func (instance *ProcessContext) ProcessId() string

func (*ProcessContext) StartedAt added in v1.19.0 

func (instance *ProcessContext) StartedAt() time.Time

type RouteRegistrar 

type RouteRegistrar func(kernelInstance kernelcontract.Kernel)

type RuntimeFlags 

type RuntimeFlags struct {
	// contains filtered or unexported fields
}

func NewRuntimeFlags 

func NewRuntimeFlags(mode string) *RuntimeFlags

func NewRuntimeFlagsWithRole added in v1.16.0 

func NewRuntimeFlagsWithRole(mode string, role string) *RuntimeFlags

func ParseRuntimeFlags 

func ParseRuntimeFlags(defaultMode string) *RuntimeFlags

func ParseRuntimeFlagsWithRole added in v1.16.0 

func ParseRuntimeFlagsWithRole(defaultMode string, defaultRole string) *RuntimeFlags

ParseRuntimeFlagsWithRole resolves the runtime mode and process role from os.Args. The mode: an explicit --mode/-mode wins, any other non-runtime argument implies cli, otherwise the configured default applies. The role: an explicit --role/-role wins over the configured default — the flag exists because melody reads configuration only from .env artifacts, never from the process environment, so a docker-compose deployment differentiates containers built from one image with `command: ["/app", "--role=worker"]`. Both flags are runtime-only: they never imply cli mode and are stripped before the cli framework parses the arguments. Any other value-taking flag placed before the command must use its --flag=value form — a foreign flag's arity is unknowable, so a space-separated value would read as the command name and end the runtime-flag region early (see subcommandBoundaryIndex).

func (*RuntimeFlags) Mode 

func (instance *RuntimeFlags) Mode() string

func (*RuntimeFlags) Role added in v1.16.0 

func (instance *RuntimeFlags) Role() string

type SecurityModule 

type SecurityModule = applicationcontract.SecurityModule

SecurityModule lives in application/contract beside its eight sibling hooks; the alias keeps every implementation and assertion written against the application package compiling.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.