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 FromEnvironment() Option
- func WithAdvertiseAddress(addr string) Option
- func WithApplication(app dogma.Application) Option
- func WithListenAddress(addr string) Option
- func WithNodeID(id string) Option
- func WithPersistence(url string) Option
- func WithPersistenceProvider(p PersistenceProvider) Option
- func WithSite(name, key string) Option
- type PersistenceProvider
Constants ¶
This section is empty.
Variables ¶
var FerriteRegistry = ferrite.NewRegistry(
"dogmatiq.runkit",
"Runkit",
)
FerriteRegistry is the ferrite environment variable registry for the Runkit engine. It can be passed to ferrite.Init() to validate Runkit's environment variables alongside the application's own variables.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine runs one or more Dogma applications.
func (*Engine) ExecutorFor ¶
func (e *Engine) ExecutorFor(app dogma.Application) dogma.CommandExecutor
ExecutorFor returns a dogma.CommandExecutor for app.
Commands executed before Engine.Run is called block until the engine starts.
It panics if app was not registered with WithApplication.
type Option ¶
type Option func(*Engine)
Option is a function that configures an Engine.
func FromEnvironment ¶
func FromEnvironment() Option
FromEnvironment returns an Option that configures the engine using environment variables.
It reads the following environment variables:
- DOGMA_SITE_NAME (see WithSite)
- DOGMA_SITE_KEY (see WithSite)
- 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, regardless of the order in which options are specified.
TODO: all of these environment variables should already be validated by Ferrite. The panics in this function are a necessary defense, but they should never be the way we expect to surface invalid environment variable values to users. We should be able to rely on Ferrite to catch these issues at startup and provide user-friendly error messages.
func WithAdvertiseAddress ¶
WithAdvertiseAddress returns an Option that sets the address the engine advertises to other nodes, in "host:port" format.
If unset, the advertise address is derived from the bind address and network interface introspection at startup.
If FromEnvironment is also used, this option takes precedence over DOGMA_ADVERTISE_ADDRESS.
It panics if addr is not a valid host:port address.
func WithApplication ¶
func WithApplication(app dogma.Application) Option
WithApplication returns an Option that registers app with the engine.
It panics if app is nil or if an application with the same identity key has already been registered.
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").
If FromEnvironment is also used, this option takes precedence over DOGMA_LISTEN_ADDRESS.
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.
id is a canonical RFC 9562 UUID string. If neither this option nor FromEnvironment supplies a node ID, the engine generates a random UUID at startup.
If FromEnvironment is also used, this option takes precedence over the value of the DOGMA_NODE_ID environment variable.
It panics if id is not a valid UUID.
func WithPersistence ¶
WithPersistence returns an Option that configures the persistence provider for the engine using a URL string.
If FromEnvironment is also used, this option takes precedence over the value of the DOGMA_PERSISTENCE_URL environment variable.
It panics if the URL is malformed or if the scheme is unrecognized.
func WithPersistenceProvider ¶
func WithPersistenceProvider(p PersistenceProvider) Option
WithPersistenceProvider returns an Option that configures the persistence provider for the engine.
If FromEnvironment is also used, this option takes precedence over the value of the DOGMA_PERSISTENCE_URL environment variable.
A persistence provider is required. Engine.Run panics if none is configured.
func WithSite ¶
WithSite 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.
If FromEnvironment is also used, this option takes precedence over the values of the DOGMA_SITE_NAME and DOGMA_SITE_KEY environment variables.
It panics if name is empty or if key is not a valid UUID.
type PersistenceProvider ¶
type PersistenceProvider = persistence.Provider
PersistenceProvider provides the persistence stores used by the engine.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
docs
|
|
|
internal
|
|
|
persistence
Package persistence abstracts the engine's durable storage behind a Provider interface, decoupling the engine from any specific storage technology.
|
Package persistence abstracts the engine's durable storage behind a Provider interface, decoupling the engine from any specific storage technology. |
|
persistence/driver/dynamodb
Package dynamodb implements the persistence.Provider interface using Amazon DynamoDB as the storage backend.
|
Package dynamodb implements the persistence.Provider interface using Amazon DynamoDB as the storage backend. |
|
persistence/driver/internal/xaws
Package xaws provides shared AWS helpers for persistence drivers.
|
Package xaws provides shared AWS helpers for persistence drivers. |
|
persistence/driver/memory
Package memory implements the persistence.Provider interface using in-process data structures.
|
Package memory implements the persistence.Provider interface using in-process data structures. |
|
persistence/driver/postgres
Package postgres implements the persistence.Provider interface using PostgreSQL as the storage backend.
|
Package postgres implements the persistence.Provider interface using PostgreSQL as the storage backend. |
|
persistence/driver/s3
Package s3 implements the persistence.Provider interface using Amazon S3 as the storage backend.
|
Package s3 implements the persistence.Provider interface using Amazon S3 as the storage backend. |
|
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. |