correlation

package

v0.8.4 Latest Latest Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Hanalyx/openwatch

Links

Open Source Insights

Documentation ¶

Overview ¶

Package correlation propagates a request-scoped correlation ID across HTTP entry, audit emission, log lines, and outbound calls.

One ID per top-level intent. See docs/engineering/correlation_id_propagation.md for the full design and specs/system/correlation.spec.yaml for the behavioral contract.

IDs are formatted as "<prefix>-<16 hex chars>", where the hex portion is the high-order 8 bytes of a UUIDv7 (so they are roughly time-ordered when sorted lexicographically). Prefixes signal origin:

req-   HTTP request
cron-  scheduled job tick
boot-  process startup
test-  test harness (reserved)

Index ¶

Constants
func From(ctx context.Context) (string, bool)
func Generate(prefix Prefix) string
func HTTPMiddleware(next http.Handler) http.Handler
func SanitizeOrGenerate(client string) (id string, regenerated bool)
func Set(ctx context.Context, id string) context.Context
type Prefix

Constants ¶

View Source

const HeaderName = "X-Correlation-Id"

HeaderName is the HTTP header carrying the correlation ID.

Variables ¶

This section is empty.

Functions ¶

func From ¶

func From(ctx context.Context) (string, bool)

From returns the correlation ID on the context, if any. The bool is false when no ID is set; callers should treat that as "logs/audit will have no correlation_id attached for this code path."

func Generate ¶

func Generate(prefix Prefix) string

Generate returns a fresh correlation ID with the given prefix.

Format: <prefix>-<16 hex chars>. The 16 hex chars are 8 bytes:

Bytes 0-5: 48-bit unix-millisecond timestamp (time-ordered when sorted)
Bytes 6-7: 16-bit monotonic counter, randomly seeded each ms

IDs sort lexicographically in time order; within the same millisecond they sort by counter (monotonically increasing, distinct).

Panics on rand.Read failure — that condition signals the OS RNG is broken, which is not recoverable.

func HTTPMiddleware ¶

func HTTPMiddleware(next http.Handler) http.Handler

HTTPMiddleware extracts (or generates) a correlation ID for every incoming request, places it on the request context, and echoes it back in the response header.

It MUST be mounted before any other middleware that emits logs or audit events. Per correlation.spec.yaml AC-9..AC-11 and the design in docs/engineering/correlation_id_propagation.md §5.1.

Rejected client headers (charset/length/reserved-prefix violations) are replaced with a freshly-generated req- ID; a warn-level log records the rejection with a truncated preview of the bad value.

func SanitizeOrGenerate ¶

func SanitizeOrGenerate(client string) (id string, regenerated bool)

SanitizeOrGenerate inspects a client-supplied X-Correlation-Id header and returns either the original (when valid) or a freshly generated req- ID. The regenerated flag is true when the input was rejected and callers may want to log a warning.

Empty input is not a rejection — it just means "no client header, generate one." Rejection happens for:

input that fails validIDPattern (charset/length)
input that starts with a reserved prefix

func Set ¶

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

Set returns a new context carrying the given correlation ID.

Types ¶

type Prefix ¶

type Prefix string

Prefix is the origin marker on a correlation ID.

const (
	PrefixRequest Prefix = "req"
	PrefixCron    Prefix = "cron"
	PrefixBoot    Prefix = "boot"
	PrefixTest    Prefix = "test"
)

Origin prefixes. boot/cron/test are reserved — clients sending these via X-Correlation-Id are rejected and regenerated.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL