README
¶
Run Kit
This repository contains the official Dogma engine, used to run Dogma applications in production environments.
Documentation
¶
Overview ¶
Package runkit is a horizontally scalable, multi-node Dogma engine.
Index ¶
- Variables
- type Engine
- type Option
- func WithAdvertiseAddress(addr string) Option
- func WithListenAddress(addr string) Option
- func WithNodeID(id string) Option
- func WithPersistence(url string) Option
- func WithPersistenceConfig(cfg persistencekit.Config) Option
- func WithSiteIdentity(name, key string) Option
- func WithoutEnvironment() Option
Constants ¶
This section is empty.
Variables ¶
var FerriteRegistry = ferrite.NewRegistry(
"dogmatiq.runkit",
"Dogma",
)
FerriteRegistry is the ferrite environment variable registry for the Runkit engine.
If the application uses ferrite to manage its environment variables, it should use ferrite.WithRegistry to include this registry in its call to ferrite.Init to ensure the application's generated documentation includes the environment variables used by the engine.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine runs a single Dogma dogma.Application.
func New ¶
func New(app dogma.Application, opts ...Option) (*Engine, error)
New returns an Engine that runs the given dogma.Application.
It panics if app is nil. It returns an error if the engine configuration is incomplete, such as when a site identity or persistence provider has not been specified.
By default, New reads the following environment variables to fill in any configuration not provided by explicit options:
- DOGMA_SITE (see WithSiteIdentity)
- DOGMA_NODE_ID (see WithNodeID)
- DOGMA_PERSISTENCE_URL (see WithPersistence)
- DOGMA_LISTEN_ADDRESS (see WithListenAddress)
- DOGMA_ADVERTISE_ADDRESS (see WithAdvertiseAddress)
Explicit options always take precedence over environment variables. Use WithoutEnvironment to disable environment variable reading entirely.
func (*Engine) ExecuteCommand ¶
func (e *Engine) ExecuteCommand( ctx context.Context, cmd dogma.Command, options ...dogma.ExecuteCommandOption, ) error
ExecuteCommand routes a command to the appropriate handler within the application. See dogma.CommandExecutor for detailed semantics.
It blocks until Engine.Run is called or ctx is canceled.
type Option ¶
type Option func(*engineConfig)
Option is a function that configures an Engine.
func WithAdvertiseAddress ¶
WithAdvertiseAddress returns an Option that sets the address the engine advertises to other nodes, in "host:port" format.
Most deployments only need WithListenAddress; the advertise address is derived from the listen address automatically. Use this option when the address visible to other nodes differs from the listen address, for example when behind a NAT or load balancer.
If no listen address is configured the engine listens on the advertise address directly.
This option takes precedence over the DOGMA_ADVERTISE_ADDRESS environment variable.
It panics if addr is not a routable host:port address. Wildcard hosts (such as 0.0.0.0 or ::) and port 0 are not permitted.
func WithListenAddress ¶
WithListenAddress returns an Option that sets the TCP address the engine listens on, in "host:port" format (e.g. "0.0.0.0:7831").
This option takes precedence over the DOGMA_LISTEN_ADDRESS environment variable.
It panics if addr is not a valid host:port address.
func WithNodeID ¶
WithNodeID returns an Option that sets the node identity for the engine.
A node represents a single running instance of the engine within a site. In a clustered deployment each host is a separate node.
This option takes precedence over the DOGMA_NODE_ID environment variable.
If neither this option nor the DOGMA_NODE_ID environment variable supplies a node ID, the engine generates a random UUID at startup.
It panics if id is not a canonical RFC 9562 UUID string.
func WithPersistence ¶
WithPersistence returns an Option that configures the persistence driver for the engine using a URL string.
This option takes precedence over the DOGMA_PERSISTENCE_URL environment variable.
It panics if the URL is malformed or if the scheme is unrecognized.
func WithPersistenceConfig ¶
func WithPersistenceConfig(cfg persistencekit.Config) Option
WithPersistenceConfig returns an Option that configures persistence using a persistencekit.Config.
This option takes precedence over the DOGMA_PERSISTENCE_URL environment variable.
It panics if cfg is nil.
func WithSiteIdentity ¶
WithSiteIdentity returns an Option that sets the site identity for the engine.
A site represents a distinct installation of the same set of applications. Separate sites are used when running independent deployments, for example:
- geographical regions (US, EU, APAC)
- environment tiers (development, staging, production)
- isolated tenants or customers
Each site has its own persisted state; two sites never share data. The site identity is included in every message envelope the engine produces.
name is a human-readable label for the site. key is a canonical RFC 9562 UUID string that uniquely identifies the site. If you're unsure, generate a new random (v4) UUID and hardcode it.
This option takes precedence over the DOGMA_SITE environment variable.
It panics if name is empty or if key is not a valid UUID.
func WithoutEnvironment ¶
func WithoutEnvironment() Option
WithoutEnvironment returns an Option that prevents the engine from reading configuration from environment variables.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
docs
|
|
|
internal
|
|
|
rendezvous
Package rendezvous implements rendezvous hashing for workload-to-candidate assignment.
|
Package rendezvous implements rendezvous hashing for workload-to-candidate assignment. |
|
x/xpersistence
Package xpersistence contains persistence utilities.
|
Package xpersistence contains persistence utilities. |
|
x/xtelemetry
Package xtelemetry provides telemetry utilities.
|
Package xtelemetry provides telemetry utilities. |
|
x/xtesting/journaltest
Package journaltest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/journal.
|
Package journaltest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/journal. |
|
x/xtesting/kvtest
Package kvtest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/kv.
|
Package kvtest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/kv. |
|
x/xtesting/settest
Package settest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/set.
|
Package settest provides utilities for testing systems that use github.com/dogmatiq/persistencekit/set. |