compat

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package compat is the Go half of the cross-language compatibility harness between this module and the Rust photon-evt crate. It defines a small account domain that both languages implement identically, runs the shared scenarios in compat/scenarios.json, and generates the golden fixtures in compat/fixtures that the Rust test suite asserts against byte for byte.

The domain deliberately keeps entity IDs out of payloads and state so fixtures can be replayed under per-run entity IDs during live integration runs.

Index

Constants

View Source
const (
	OpenedEvent    evt.EventType = "account:opened"
	DepositedEvent evt.EventType = "account:deposited"
	WithdrawnEvent evt.EventType = "account:withdrawn"
	TaggedEvent    evt.EventType = "account:tagged"
	LabeledEvent   evt.EventType = "account:labeled"
	RenamedEvent   evt.EventType = "account:renamed"
	ClosedEvent    evt.EventType = "account:closed"
)

Event types and their current versions.

View Source
const (
	CodecFixtureFile    = "codec.json"
	ScenarioFixtureFile = "scenarios.json"
)

Fixture file names under compat/fixtures.

View Source
const (
	WriterGo   = "go"
	WriterRust = "rust"
)

Writer names used in scenario steps and recorded as the metadata origin endpoint.

View Source
const (
	OriginSource     = "evt-compat"
	Region           = "us-west-2"
	DefaultTimestamp = "2026-10-12T00:00:00Z"
	FixtureRun       = "fixture"
)

Shared metadata values. Every step's metadata is fully determined by the step, so the bytes each language writes are comparable.

View Source
const (
	ResultOK        = "ok"
	ResultRejected  = "rejected"
	ResultDuplicate = "duplicate"
	ResultConflict  = "conflict"
	ResultCompacted = "compacted"
	ResultUncovered = "uncovered"
)

Step results.

View Source
const AccountType evt.EntityType = "account"

AccountType is the entity type of the shared account aggregate.

Variables

This section is empty.

Functions

func Dir

func Dir() string

Dir returns the repository's compat/ directory.

func DynamoItemJSON

func DynamoItemJSON(item map[string]types.AttributeValue) map[string]any

DynamoItemJSON renders an item as DynamoDB JSON.

func DynamoJSON

func DynamoJSON(value types.AttributeValue) any

DynamoJSON renders an attribute value as DynamoDB JSON.

func EntityID

func EntityID(run string, scenario Scenario) evt.EntityID

EntityID is the stream ID for a scenario within a run.

func FixturePath

func FixturePath(name string) string

FixturePath returns the path of a fixture file.

func MarshalFixture

func MarshalFixture(value any) ([]byte, error)

MarshalFixture encodes a fixture file: two-space indent, no HTML escaping, trailing newline.

func SNSMessage

func SNSMessage(ctx context.Context, item map[string]types.AttributeValue) (string, map[string]string, error)

SNSMessage publishes an event-log item through the real stream.SNSPublisher (as a DynamoDB stream INSERT) and returns the message body and string attributes it sent.

func StepMetadata

func StepMetadata(step Step) evt.Metadata

StepMetadata builds the metadata for a step.

Types

type Account

type Account struct {
	Owner        string            `json:"owner"`
	Status       string            `json:"status"`
	BalanceCents int64             `json:"balanceCents"`
	Deposits     int64             `json:"deposits"`
	OpenedAt     time.Time         `json:"openedAt"`
	Tags         []string          `json:"tags"`
	Labels       map[string]string `json:"labels"`
	LastMemo     *string           `json:"lastMemo"`
	// contains filtered or unexported fields
}

Account is the shared aggregate. Its JSON encoding is the snapshot format, so the Rust struct declares the same fields in the same order.

func NewAccount

func NewAccount(id evt.EntityID) *Account

NewAccount returns an empty account for the given entity ID.

func (*Account) Apply

func (a *Account) Apply(event evt.Event) error

Apply folds an event into state.

func (*Account) Base

func (a *Account) Base() evt.BaseEntity

Base returns the base entity fields.

func (*Account) DeserializeEvent

func (a *Account) DeserializeEvent(serialized evt.SerializedEvent) (evt.Event, error)

DeserializeEvent decodes a stored payload into its typed event.

func (*Account) EventUpcasters

func (a *Account) EventUpcasters() []evt.EventUpcaster

EventUpcasters migrates account:renamed v1 to v2.

func (*Account) GetID

func (a *Account) GetID() evt.EntityID

GetID returns the entity ID.

func (*Account) Handle

func (a *Account) Handle(_ context.Context, command evt.Command) (evt.CommandResult, error)

Handle decides the events for a command. The rules must match the Rust implementation.

func (*Account) Projectors

func (a *Account) Projectors() []evt.EventProjector

Projectors returns no in-band projectors.

func (*Account) SetID

func (a *Account) SetID(id evt.EntityID)

SetID sets the entity ID. The store calls it after loading.

func (*Account) Type

func (a *Account) Type() evt.EntityType

Type returns the account entity type.

type AccountClosed

type AccountClosed struct {
	Reason *string `json:"reason"`
}

AccountClosed is the payload of account:closed (v1).

func (AccountClosed) EntityID

func (AccountClosed) EntityID() evt.EntityID

func (AccountClosed) EntityType

func (AccountClosed) EntityType() evt.EntityType

func (AccountClosed) Type

func (AccountClosed) Type() evt.EventType

func (AccountClosed) Version

func (AccountClosed) Version() evt.EventVersion

type AccountLabeled

type AccountLabeled struct {
	Labels map[string]string `json:"labels"`
}

AccountLabeled is the payload of account:labeled (v1).

func (AccountLabeled) EntityID

func (AccountLabeled) EntityID() evt.EntityID

func (AccountLabeled) EntityType

func (AccountLabeled) EntityType() evt.EntityType

func (AccountLabeled) Type

func (AccountLabeled) Type() evt.EventType

func (AccountLabeled) Version

func (AccountLabeled) Version() evt.EventVersion

type AccountOpened

type AccountOpened struct {
	Owner    string    `json:"owner"`
	OpenedAt time.Time `json:"openedAt"`
}

AccountOpened is the payload of account:opened (v1).

func (AccountOpened) EntityID

func (AccountOpened) EntityID() evt.EntityID

Events carry no entity ID. The store assigns it when serializing.

func (AccountOpened) EntityType

func (AccountOpened) EntityType() evt.EntityType

func (AccountOpened) Type

func (AccountOpened) Type() evt.EventType

func (AccountOpened) Version

func (AccountOpened) Version() evt.EventVersion

type AccountRenamed

type AccountRenamed struct {
	Owner string `json:"owner"`
}

AccountRenamed is the payload of account:renamed (v2). Version 1 stored the owner as "name".

func (AccountRenamed) EntityID

func (AccountRenamed) EntityID() evt.EntityID

func (AccountRenamed) EntityType

func (AccountRenamed) EntityType() evt.EntityType

func (AccountRenamed) Type

func (AccountRenamed) Type() evt.EventType

func (AccountRenamed) Version

func (AccountRenamed) Version() evt.EventVersion

type AccountTagged

type AccountTagged struct {
	Tags []string `json:"tags"`
}

AccountTagged is the payload of account:tagged (v1).

func (AccountTagged) EntityID

func (AccountTagged) EntityID() evt.EntityID

func (AccountTagged) EntityType

func (AccountTagged) EntityType() evt.EntityType

func (AccountTagged) Type

func (AccountTagged) Type() evt.EventType

func (AccountTagged) Version

func (AccountTagged) Version() evt.EventVersion

type CodecFixtures

type CodecFixtures struct {
	Events         []EventVector    `json:"events"`
	Snapshots      []SnapshotVector `json:"snapshots"`
	MetadataDecode []DecodeVector   `json:"metadataDecode"`
	EventDecode    []DecodeVector   `json:"eventDecode"`
	SnapshotPolicy [][4]int64       `json:"snapshotPolicy"`
	Views          []ViewVector     `json:"views"`
	IntKeyMap      string           `json:"intKeyMap"`
	TTL            TTLVector        `json:"ttl"`
}

CodecFixtures pins the encoding of individual events, snapshots, and metadata.

func GenerateCodecFixtures

func GenerateCodecFixtures(ctx context.Context) (CodecFixtures, error)

GenerateCodecFixtures encodes every codec case through the Go implementation: JSON via encoding/json, DynamoDB items via the real repository, and SNS messages via the real publisher.

type Command

type Command struct {
	Kind        string            `json:"type"`
	Owner       string            `json:"owner"`
	OpenedAt    string            `json:"openedAt"`
	AmountCents int64             `json:"amountCents"`
	Amounts     []int64           `json:"amounts"`
	Memo        *string           `json:"memo"`
	Tags        []string          `json:"tags"`
	Labels      map[string]string `json:"labels"`
	Reason      *string           `json:"reason"`
}

Command is the account command, decoded from a scenario step. Kind selects the operation.

func (*Command) EntityType

func (c *Command) EntityType() evt.EntityType

EntityType returns the account entity type.

func (*Command) Type

func (c *Command) Type() evt.CommandType

Type returns the command type.

type DecodeVector

type DecodeVector struct {
	Name      string `json:"name"`
	Input     string `json:"input"`
	Canonical string `json:"canonical"`
}

DecodeVector is a JSON input and its canonical re-encoding after a lenient decode.

type EventInput

type EventInput struct {
	ID           evt.EventID       `json:"id"`
	Sequence     evt.EventSequence `json:"sequence"`
	Type         evt.EventType     `json:"type"`
	Version      evt.EventVersion  `json:"version"`
	EntityID     evt.EntityID      `json:"entityId"`
	EntityType   evt.EntityType    `json:"entityType"`
	Payload      string            `json:"payload"`
	MetadataJSON string            `json:"metadataJson"`
}

EventInput describes a serialized event field by field. Metadata is given as its Go encoding.

type EventVector

type EventVector struct {
	Name                string            `json:"name"`
	Input               EventInput        `json:"input"`
	SerializedEventJSON string            `json:"serializedEventJson"`
	DynamoItem          map[string]any    `json:"dynamoItem"`
	SNSMessage          string            `json:"snsMessage"`
	SNSAttributes       map[string]string `json:"snsAttributes"`
}

EventVector is one event and every encoding of it.

type FakeDynamo

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

FakeDynamo is an in-memory DynamoDB table that understands exactly the key conditions and condition expressions the evt DynamoDB repository issues. It lets the golden fixtures come from the real dynamo.Repository write path without an emulator.

func NewFakeDynamo

func NewFakeDynamo() *FakeDynamo

NewFakeDynamo returns an empty table.

func (*FakeDynamo) BatchGetItem

BatchGetItem is not supported.

func (*FakeDynamo) BatchWriteItem

func (f *FakeDynamo) BatchWriteItem(
	_ context.Context,
	params *dynamodb.BatchWriteItemInput,
	_ ...func(*dynamodb.Options),
) (*dynamodb.BatchWriteItemOutput, error)

BatchWriteItem applies delete requests.

func (*FakeDynamo) DeleteItem

DeleteItem is not supported.

func (*FakeDynamo) ExportTableToPointInTime

ExportTableToPointInTime is not supported.

func (*FakeDynamo) GetItem

func (f *FakeDynamo) GetItem(
	_ context.Context,
	params *dynamodb.GetItemInput,
	_ ...func(*dynamodb.Options),
) (*dynamodb.GetItemOutput, error)

GetItem reads one item by key.

func (*FakeDynamo) Items

func (f *FakeDynamo) Items(pk string) []map[string]types.AttributeValue

Items returns every item in a partition, ascending by sort key (the snapshot at sk=0 first).

func (*FakeDynamo) PutItem

func (f *FakeDynamo) PutItem(
	_ context.Context,
	params *dynamodb.PutItemInput,
	_ ...func(*dynamodb.Options),
) (*dynamodb.PutItemOutput, error)

PutItem writes one item when its condition holds.

func (*FakeDynamo) Query

func (f *FakeDynamo) Query(
	_ context.Context,
	params *dynamodb.QueryInput,
	_ ...func(*dynamodb.Options),
) (*dynamodb.QueryOutput, error)

Query supports `pk = :pk AND sk > :sk` and `pk = :pk AND sk BETWEEN :lo AND :hi`, with ScanIndexForward and Limit. It returns everything in one page.

func (*FakeDynamo) Scan

Scan is not supported. The harness never scans.

func (*FakeDynamo) TransactWriteItems

func (f *FakeDynamo) TransactWriteItems(
	_ context.Context,
	params *dynamodb.TransactWriteItemsInput,
	_ ...func(*dynamodb.Options),
) (*dynamodb.TransactWriteItemsOutput, error)

TransactWriteItems applies puts atomically, cancelling the whole transaction on any failed condition with the same exception shape DynamoDB returns.

func (*FakeDynamo) UpdateItem

UpdateItem is not supported.

type MoneyDeposited

type MoneyDeposited struct {
	AmountCents int64   `json:"amountCents"`
	Memo        *string `json:"memo"`
}

MoneyDeposited is the payload of account:deposited (v1).

func (MoneyDeposited) EntityID

func (MoneyDeposited) EntityID() evt.EntityID

func (MoneyDeposited) EntityType

func (MoneyDeposited) EntityType() evt.EntityType

func (MoneyDeposited) Type

func (MoneyDeposited) Type() evt.EventType

func (MoneyDeposited) Version

func (MoneyDeposited) Version() evt.EventVersion

type MoneyWithdrawn

type MoneyWithdrawn struct {
	AmountCents int64 `json:"amountCents"`
}

MoneyWithdrawn is the payload of account:withdrawn (v1).

func (MoneyWithdrawn) EntityID

func (MoneyWithdrawn) EntityID() evt.EntityID

func (MoneyWithdrawn) EntityType

func (MoneyWithdrawn) EntityType() evt.EntityType

func (MoneyWithdrawn) Type

func (MoneyWithdrawn) Type() evt.EventType

func (MoneyWithdrawn) Version

func (MoneyWithdrawn) Version() evt.EventVersion

type Outcome

type Outcome struct {
	Result  string `json:"result"`
	Events  int    `json:"events,omitempty"`
	Deleted int    `json:"deleted,omitempty"`
}

Outcome is the observable result of a step.

func (Outcome) String

func (o Outcome) String() string

type RawEvent

type RawEvent struct {
	Type    evt.EventType    `json:"type"`
	Version evt.EventVersion `json:"version"`
	Payload string           `json:"payload"`
}

RawEvent is an event appended directly to the log, bypassing the aggregate (legacy versions).

type RejectedError

type RejectedError struct {
	Reason string
}

RejectedError is a business-rule rejection. Both languages reject the same commands.

func (*RejectedError) Error

func (e *RejectedError) Error() string

type Runner

type Runner struct {
	Store            evt.Store
	Repo             evt.Repository
	SnapshotInterval int
}

Runner executes steps against one backend.

func (Runner) Execute

func (r Runner) Execute(ctx context.Context, entityID evt.EntityID, step Step) (Outcome, error)

Execute runs one step and classifies its outcome. Unexpected errors are returned as errors.

type Scenario

type Scenario struct {
	Name             string `json:"name"`
	Description      string `json:"description"`
	SnapshotInterval int    `json:"snapshotInterval"`
	Steps            []Step `json:"steps"`
}

Scenario is one stream driven by a sequence of steps, each assigned to a writer language.

type ScenarioExpectation

type ScenarioExpectation struct {
	Name             string           `json:"name"`
	EntityID         evt.EntityID     `json:"entityId"`
	Sequence         int64            `json:"sequence"`
	SnapshotSequence int64            `json:"snapshotSequence"`
	State            string           `json:"state"`
	Events           []string         `json:"events"`
	Snapshot         *string          `json:"snapshot"`
	DynamoItems      []map[string]any `json:"dynamoItems"`
	SNSMessages      []string         `json:"snsMessages"`
}

ScenarioExpectation is the stored and loaded state of a scenario's stream after all steps.

func Observe

func Observe(ctx context.Context, runner Runner, name string, entityID evt.EntityID) (ScenarioExpectation, error)

Observe reads a stream back through the repository and store: the stored events and snapshot, and the loaded state. DynamoItems and SNSMessages are left empty.

func (ScenarioExpectation) ForRun

ForRun rewrites the expectation's entity IDs from the fixture run to another run.

type ScenarioFixtures

type ScenarioFixtures struct {
	Run       string                `json:"run"`
	Source    string                `json:"source"`
	Scenarios []ScenarioExpectation `json:"scenarios"`
}

ScenarioFixtures is the golden output of every shared scenario, produced by the Go implementation and asserted by both languages.

func GenerateScenarioFixtures

func GenerateScenarioFixtures(ctx context.Context, scenarios Scenarios) (ScenarioFixtures, error)

GenerateScenarioFixtures runs every scenario through the Go implementation against a fake DynamoDB table, checks each step's expected outcome, and records the final state.

func LoadScenarioFixtures

func LoadScenarioFixtures() (ScenarioFixtures, error)

LoadScenarioFixtures reads compat/fixtures/scenarios.json.

type Scenarios

type Scenarios struct {
	Scenarios []Scenario `json:"scenarios"`
}

Scenarios is the shared scenario file (compat/scenarios.json).

func LoadScenarios

func LoadScenarios() (Scenarios, error)

LoadScenarios reads compat/scenarios.json.

type SnapshotInput

type SnapshotInput struct {
	EntityType    evt.EntityType    `json:"entityType"`
	EntityID      evt.EntityID      `json:"entityId"`
	Sequence      evt.EventSequence `json:"sequence"`
	EventSequence evt.EventSequence `json:"eventSequence"`
	Payload       string            `json:"payload"`
}

SnapshotInput describes a serialized snapshot.

type SnapshotVector

type SnapshotVector struct {
	Name                   string         `json:"name"`
	Input                  SnapshotInput  `json:"input"`
	SerializedSnapshotJSON string         `json:"serializedSnapshotJson"`
	DynamoItem             map[string]any `json:"dynamoItem"`
}

SnapshotVector is one snapshot and its encodings.

type Step

type Step struct {
	By        string            `json:"by"`
	Op        string            `json:"op"`
	CommandID string            `json:"commandId,omitempty"`
	Command   *Command          `json:"command,omitempty"`
	Event     *RawEvent         `json:"event,omitempty"`
	Through   int64             `json:"through,omitempty"`
	Sequence  int64             `json:"sequence,omitempty"`
	Trace     map[string]string `json:"trace,omitempty"`
	Address   string            `json:"address,omitempty"`
	Timestamp string            `json:"timestamp,omitempty"`
	Expect    Outcome           `json:"expect"`
}

Step is one operation against the scenario's stream.

type TTLStream

type TTLStream struct {
	Name           string           `json:"name"`
	RetentionNanos int64            `json:"retentionNanos"`
	Events         []string         `json:"events"`
	Snapshot       string           `json:"snapshot"`
	DynamoItems    []map[string]any `json:"dynamoItems"`
}

TTLStream is one committed stream and the items it produced, snapshot first.

type TTLVector

type TTLVector struct {
	ClockUnixNano int64       `json:"clockUnixNano"`
	Streams       []TTLStream `json:"streams"`
}

TTLVector pins the retention policy: streams committed with a snapshot through a repository with a fixed clock, one stream per policy (a duration, zero, and none).

type ViewVector

type ViewVector struct {
	Name       string         `json:"name"`
	EntityID   evt.EntityID   `json:"entityId"`
	State      string         `json:"state"`
	DynamoItem map[string]any `json:"dynamoItem"`
}

ViewVector is the single-item view row dynamo.NewViewProjector writes for an account.

Directories

Path Synopsis
cmd
evt-compat command
Command evt-compat is the Go driver for the cross-language integration run (scripts/compat-integration.sh).
Command evt-compat is the Go driver for the cross-language integration run (scripts/compat-integration.sh).

Jump to

Keyboard shortcuts

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