core

Documentation

Overview

Package core provides foundational primitives shared across MicroJet: an injectable time/clock abstraction, correlation-ID propagation, and the service lifecycle interfaces (Initer, Starter, Closer, HealthChecker).

Index

• Constants
• func ContextWithCorrelationID(ctx context.Context, id string) context.Context
• func CorrelationIDFromContext(ctx context.Context) string
• func SortableMSToTime(st string) time.Time
• func SortableToTime(st string) time.Time
• func TimeToSortable(t time.Time) string
• func TimeToSortableMS(t time.Time) string
• func TruncateToSecond(t time.Time) time.Time
• type Clock
  • func NewClock(now NowProvider) *Clock
  • func (c *Clock) Now() time.Time
  • func (c *Clock) NowSortable() string
  • func (c *Clock) NowSortableMS() string
  • func (c *Clock) NowTS() int64
• type Closer
• type FixedClock
  • func NewFixedClock(t time.Time) *FixedClock
  • func (c *FixedClock) Advance(d time.Duration)
  • func (c *FixedClock) Set(t time.Time)
• type HealthChecker
• type Initer
• type NowProvider
• type ReadinessToggler
• type Setupper
• type Starter
• type TimeProvider

Constants

const CorrelationIDHeader = "X-Request-ID"

CorrelationIDHeader is the canonical header carrying a correlation (request) id across process boundaries — HTTP requests and message broker frames alike. httpx and messaging both read and write this header so an id flows uniformly http -> messaging -> http.

Functions

func ContextWithCorrelationID

func ContextWithCorrelationID(ctx context.Context, id string) context.Context

ContextWithCorrelationID returns a copy of ctx carrying the correlation id. It is the single source of truth for the correlation-id context key, shared by every MicroJet layer so the id survives across http and messaging hops.

func CorrelationIDFromContext

func CorrelationIDFromContext(ctx context.Context) string

CorrelationIDFromContext returns the correlation id stored in ctx, or "" if none is present.

func SortableMSToTime

func SortableMSToTime(st string) time.Time

func SortableToTime

func SortableToTime(st string) time.Time

func TimeToSortable

func TimeToSortable(t time.Time) string

func TimeToSortableMS

func TimeToSortableMS(t time.Time) string

TimeToSortableMS formats t as a 17-digit lexicographically sortable string with millisecond precision: YYYYMMDDHHMMSSmmm. Go only recognizes fractional seconds when preceded by a separator, so we format with a dot and strip it.

func TruncateToSecond

func TruncateToSecond(t time.Time) time.Time

Types

type Clock

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

func NewClock

func NewClock(now NowProvider) *Clock

func (*Clock) Now

func (c *Clock) Now() time.Time

func (*Clock) NowSortable

func (c *Clock) NowSortable() string

func (*Clock) NowSortableMS

func (c *Clock) NowSortableMS() string

func (*Clock) NowTS

func (c *Clock) NowTS() int64

type Closer

type Closer interface {
	Close() error
}

Closer is implemented by services that need to release resources on shutdown. The host calls Close on each registered service that implements this interface (host.ServiceCloser takes precedence when present).

type FixedClock

type FixedClock struct {
	*Clock
	Time time.Time
}

FixedClock is a TimeProvider that reports a preset time, for deterministic tests. It is not safe for concurrent mutation; set the time before use.

func NewFixedClock

func NewFixedClock(t time.Time) *FixedClock

func (*FixedClock) Advance

func (c *FixedClock) Advance(d time.Duration)

Advance moves the clock forward by d.

func (*FixedClock) Set

func (c *FixedClock) Set(t time.Time)

Set replaces the time the clock reports.

type HealthChecker

type HealthChecker interface {
	Healthy(ctx context.Context) error
}

HealthChecker is implemented by services that can report whether they are ready to serve traffic. The host's /readyz probe consults every registered service implementing it, so databases, cache, messaging, and any user service that implements this interface are covered without per-type wiring. Healthy returns nil when ready and a self-describing error otherwise.

type Initer

type Initer interface {
	Init() error
}

Initer is implemented by services that need to perform initialization after their config is loaded but do not require host-level DI. The host calls Init on each registered service that implements this interface (host.ServiceIniter, which carries *App, takes precedence).

type NowProvider

type NowProvider func() time.Time

type ReadinessToggler

type ReadinessToggler interface {
	SetReady(ready bool)
}

ReadinessToggler is implemented by services whose readiness can be flipped — typically an HTTP server backing /readyz. At the start of graceful shutdown the host flips every such service to not-ready and waits app.shutdownDelay before tearing anything down, so Kubernetes drops the pod from its endpoints (and load balancers stop routing new requests) before in-flight work is drained. Liveness (/health) must stay healthy throughout, or the kubelet restarts the pod mid-drain.

type Setupper

type Setupper interface {
	Setup() error
}

Setupper is implemented by services that need to perform post-init work once every service has finished Init — typically work that depends on other services being connected (running migrations, finalizing route registration). It runs in the same phase as host.App.Setup handlers but is co-located on the service itself. The host calls Setup on each registered service implementing this interface (host.ServiceSetupper, which carries *App, takes precedence).

type Starter

type Starter interface {
	Start() error
}

Starter is implemented by services that begin active work (serving, listening) only after every service has finished Init. Splitting Start from Init gives the host a window between "resources acquired" and "serving" in which setup work (migrations, route registration) can run. The host calls Start on each registered service implementing this interface (host.ServiceStarter, which carries *App, takes precedence).

type TimeProvider

type TimeProvider interface {
	Now() time.Time
	NowTS() int64
	NowSortable() string
	NowSortableMS() string
}

TimeProvider supplies the current time. Inject it (e.g. via host.WithClock) so time-dependent code can be made deterministic in tests by swapping in a FixedClock instead of reaching for time.Now() directly.

var (
	UTC   TimeProvider = NewClock(func() time.Time { return time.Now().UTC() })
	Local TimeProvider = NewClock(func() time.Time { return time.Now() })
)

UTC is the default real-time clock, used when no clock is injected.