journalcodec

Documentation

Overview

Package journalcodec owns version validation for internal journal bodies. Application definition versions are separate from these schema versions.

Index

• Constants
• Variables
• func Decode[T any](body []byte) (T, error)
• func Encode(body any) (canonical.Value, error)
• func Version(body []byte) (int, error)
• type ApplicationEventBody
  • func DecodeApplicationEvent(body []byte) (ApplicationEventBody, error)
• type AttemptConcludedBody
• type AttemptStartedBody
• type CommandCreatedBody
• type CommandSucceededBody
• type EventWaitBody
• type RunFailingBody
• type RunStartedBody
• type TerminalEventBody

Constants

const (
	ApplicationEventBodyVersion     = 1
	MaxApplicationEventPayloadBytes = 64 << 10
)

Variables

var ErrVersion = errors.New("journal body requires a positive integer v")

Functions

func Decode

func Decode[T any](body []byte) (T, error)

func Encode

func Encode(body any) (canonical.Value, error)

func Version

func Version(body []byte) (int, error)

Types

type ApplicationEventBody

type ApplicationEventBody struct {
	V       int             `json:"v"`
	Payload json.RawMessage `json:"payload"`
}

func DecodeApplicationEvent

func DecodeApplicationEvent(body []byte) (ApplicationEventBody, error)

DecodeApplicationEvent decodes the hot-path application-event envelope once. The exact envelope check relies on Flow's canonical journal write boundary; replay separately reconstructs canonical bodies for full diagnostics.

type AttemptConcludedBody

type AttemptConcludedBody struct {
	V                int        `json:"v"`
	AttemptID        string     `json:"attempt_id"`
	CommandID        string     `json:"command_id"`
	CommandKey       string     `json:"command_key"`
	Attempt          int        `json:"attempt"`
	Classification   string     `json:"classification"`
	ConsumedBudget   bool       `json:"consumed_budget"`
	ConsumedAttempts int        `json:"consumed_attempts"`
	FinishedAt       time.Time  `json:"finished_at"`
	NextAttemptAt    *time.Time `json:"next_attempt_at,omitempty"`
	ErrorCode        string     `json:"error_code,omitempty"`
	ErrorMessage     string     `json:"error_message,omitempty"`
}

type AttemptStartedBody

type AttemptStartedBody struct {
	V                int       `json:"v"`
	AttemptID        string    `json:"attempt_id"`
	CommandID        string    `json:"command_id"`
	CommandKey       string    `json:"command_key"`
	Attempt          int       `json:"attempt"`
	StartedAt        time.Time `json:"started_at"`
	Worker           string    `json:"worker"`
	LeaseDurationMS  int64     `json:"lease_duration_ms"`
	ConsumedAttempts int       `json:"consumed_attempts"`
	BudgetStartedAt  time.Time `json:"budget_started_at"`
}

type CommandCreatedBody

type CommandCreatedBody struct {
	V                      int             `json:"v"`
	CommandID              string          `json:"command_id"`
	CommandKey             string          `json:"command_key"`
	Name                   string          `json:"name"`
	Version                int             `json:"version"`
	Args                   json.RawMessage `json:"args"`
	ParentCommandID        string          `json:"parent_command_id,omitempty"`
	InitialState           string          `json:"initial_state"`
	Queue                  string          `json:"queue"`
	AttemptTimeoutMS       *int64          `json:"attempt_timeout_ms,omitempty"`
	RecoveryLeaseMS        *int64          `json:"recovery_lease_ms,omitempty"`
	RetryPolicy            json.RawMessage `json:"retry_policy"`
	InitialDelayMS         *int64          `json:"initial_delay_ms,omitempty"`
	BudgetStartedAt        *time.Time      `json:"budget_started_at,omitempty"`
	NextAttemptAt          *time.Time      `json:"next_attempt_at,omitempty"`
	DeclarationFingerprint string          `json:"declaration_fingerprint"`
	Waits                  []EventWaitBody `json:"waits,omitempty"`
	WithinMS               *int64          `json:"within_ms,omitempty"`
}

type CommandSucceededBody

type CommandSucceededBody struct {
	V             int             `json:"v"`
	CommandKey    string          `json:"command_key"`
	Result        json.RawMessage `json:"result"`
	CommitApplied bool            `json:"commit_applied"`
}

type EventWaitBody

type EventWaitBody struct {
	Name string `json:"name"`
	Key  string `json:"key"`
}

type RunFailingBody

type RunFailingBody struct {
	V          int      `json:"v"`
	Status     string   `json:"status"`
	Reason     string   `json:"reason"`
	CommandKey string   `json:"command_key"`
	Survivors  []string `json:"survivors"`
}

type RunStartedBody

type RunStartedBody struct {
	V                 int        `json:"v"`
	RunID             string     `json:"run_id"`
	DefinitionName    string     `json:"definition_name"`
	DefinitionVersion int        `json:"definition_version"`
	RunKey            string     `json:"run_key"`
	KeyScope          string     `json:"key_scope,omitempty"`
	DeadlineMode      string     `json:"deadline_mode"`
	DeadlineDuration  int64      `json:"deadline_duration_ms,omitempty"`
	DeadlineAt        *time.Time `json:"deadline_at,omitempty"`
	MaxCommands       int        `json:"max_commands"`
}

RunStartedBody is the versioned logical start record retained by the journal. Raw JSON fields already contain canonical application values.

type TerminalEventBody

type TerminalEventBody struct {
	V          int    `json:"v"`
	Status     string `json:"status"`
	Code       string `json:"code,omitempty"`
	Reason     string `json:"reason,omitempty"`
	CommandKey string `json:"command_key,omitempty"`
}