envelope

README

archon-event-envelope

Versioned event envelopes with dual-read for legacy bare JSON.

Part of the Archon open-source toolkit by @diogoX451.

Install

go get github.com/diogoX451/archon-event-envelope@latest

Usage

import "github.com/diogoX451/archon-event-envelope"

raw, _ := envelope.MarshalV1("order.created", "tenant-1", "wf-1", "corr-1", map[string]any{
    "id": "42",
})

env, bare, err := envelope.UnmarshalFlexible(raw)
// bare == false for versioned envelopes; true for legacy payloads

Why

Agent platforms and microservices evolve wire formats. Dual-read lets you ship schema_version without breaking older publishers.

Related Archon packages

Package	Role
archon-nats-bus	JetStream bus with resilient resubscribe
archon-executor-runtime	Need consumer SDK
archon-need-protocol	Need/response contracts

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.

Documentation

Overview

Package envelope provides versioned event wrappers with dual-read support for legacy bare JSON payloads.

Extracted from the Archon agent platform (https://github.com/diogoX451).

Index

• Constants
• func DecodePayload(env Envelope, dest any) error
• func MarshalV1(eventType, tenantID, workflowID, correlationID string, payload any) ([]byte, error)
• func SupportedSchema(version int) bool
• type Envelope
  • func UnmarshalFlexible(data []byte) (env Envelope, bare bool, err error)

Constants

const CurrentSchemaVersion = 1

CurrentSchemaVersion is the envelope version this package understands fully.

Functions

func DecodePayload

func DecodePayload(env Envelope, dest any) error

DecodePayload unmarshals env.Payload into dest.

func MarshalV1

func MarshalV1(eventType, tenantID, workflowID, correlationID string, payload any) ([]byte, error)

MarshalV1 wraps payload as a schema_version=1 envelope.

func SupportedSchema

func SupportedSchema(version int) bool

SupportedSchema reports whether this binary can process the version.

Types

type Envelope

type Envelope struct {
	SchemaVersion int             `json:"schema_version"`
	Type          string          `json:"type"`
	TenantID      string          `json:"tenant_id,omitempty"`
	CorrelationID string          `json:"correlation_id,omitempty"`
	WorkflowID    string          `json:"workflow_id,omitempty"`
	OccurredAt    time.Time       `json:"occurred_at"`
	Payload       json.RawMessage `json:"payload"`
}

Envelope is the versioned wrapper for cross-process events and needs. Dual-read consumers: try UnmarshalFlexible; if no envelope fields, treat raw JSON as the payload itself (legacy).

func UnmarshalFlexible

func UnmarshalFlexible(data []byte) (env Envelope, bare bool, err error)

UnmarshalFlexible decodes either a versioned envelope or legacy bare payload. When bare, schemaVersion is 0 and eventType is empty.