application

package
v3.13.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 54 Imported by: 0

Documentation

Overview

Package application provides the high-level application bootstrap, module registration, and run modes.

Index

Constants

View Source 
const (
	MiddlewareGroupHttp = "http"

	MiddlewarePriorityStatic = -1000
	MiddlewareNameStatic     = "static"

	MiddlewarePriorityDefault = 0
)
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 

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 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 ProcessRoleMustFromContainer added in v3.10.0 

func ProcessRoleMustFromContainer(serviceContainer containercontract.Container) string

func ProcessRoleMustFromResolver added in v3.10.0 

func ProcessRoleMustFromResolver(resolver containercontract.Resolver) string

Types

type Application 

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

func NewApplication 

func NewApplication(
	ctx context.Context,
	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) Configuration added in v3.9.0 

func (instance *Application) Configuration() configcontract.Configuration

Configuration exposes the loaded configuration before boot so wiring code (module 

construction in the composition root) can read parameters — including the values
melody auto-registers from the .env files — without reaching for os.Getenv. Services
resolved from the container should instead read config through the resolver.

func (*Application) MarkParameterSecret added in v3.12.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) MustRegister added in v3.12.0 

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

func (*Application) OnHttpShutdown added in v3.10.0 

func (instance *Application) OnHttpShutdown(hook func())

OnHttpShutdown registers a callback that runs as soon as the http server begins shutting down, before it waits for connections to drain. It is how an application unwinds handlers the server cannot: `http.Server.Shutdown` neither cancels the contexts of in-flight requests nor tracks hijacked connections, so a Server-Sent Events stream or a websocket blocks the whole shutdown timeout and is then cut mid-flight. Closing the hub those handlers select on (`ServerSentEventHub.Shutdown`) releases them at once.

func (*Application) ProcessRole added in v3.10.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.

func (*Application) Register added in v3.12.0 

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

Register makes the application a container registrar, so a module may reach for the container's own registration helpers — container.MustRegisterType and the generated wiring built on it — instead of only the name-based RegisterService. A duplicate is absorbed into the aggregated boot report rather than returned, so a module that registers a service the framework already provides reports it the same way whichever entry point it used.

func (*Application) RegisterCliCommand 

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

func (*Application) RegisterConfiguration added in v3.1.0 

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

func (*Application) RegisterHttpHandlerDecorator added in v3.9.0 

func (instance *Application) RegisterHttpHandlerDecorator(decorator applicationcontract.HttpHandlerDecorator)

RegisterHttpHandlerDecorator adds an outermost wrapper around the nethttp.Handler the http kernel produces. Decorators observe the full request lifecycle — including security denials and other kernel.request short-circuits that never reach the middlewares — which is where observability wrappers belong. The first registered decorator is the outermost.

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

func (*Application) RegisterModule 

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

func (*Application) RegisterModuleProvider added in v3.7.0 

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

func (*Application) RegisterParameter 

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

func (*Application) RegisterSecretParameter added in v3.12.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()

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 HttpShutdownConfiguration added in v3.7.0 

type HttpShutdownConfiguration interface {
	GetShutdownTimeout() time.Duration
}

type HttpTimeoutConfiguration added in v3.5.0 

type HttpTimeoutConfiguration interface {
	GetReadTimeout() time.Duration

	GetReadHeaderTimeout() time.Duration

	GetWriteTimeout() time.Duration

	GetIdleTimeout() time.Duration

	GetMaxHeaderBytes() int
}

type MiddlewareFactory 

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

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 v3.10.0 

func NewRuntimeFlagsWithRole(mode string, role string) *RuntimeFlags

func ParseRuntimeFlags 

func ParseRuntimeFlags(defaultMode string) *RuntimeFlags

func ParseRuntimeFlagsWithRole added in v3.10.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 v3.10.0 

func (instance *RuntimeFlags) Role() string

type SecurityModule 

type SecurityModule interface {
	applicationcontract.Module
	RegisterSecurity(builder *securityconfig.Builder)
}

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.