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
- func Dir() string
- func DynamoItemJSON(item map[string]types.AttributeValue) map[string]any
- func DynamoJSON(value types.AttributeValue) any
- func EntityID(run string, scenario Scenario) evt.EntityID
- func FixturePath(name string) string
- func MarshalFixture(value any) ([]byte, error)
- func SNSMessage(ctx context.Context, item map[string]types.AttributeValue) (string, map[string]string, error)
- func StepMetadata(step Step) evt.Metadata
- type Account
- func (a *Account) Apply(event evt.Event) error
- func (a *Account) Base() evt.BaseEntity
- func (a *Account) DeserializeEvent(serialized evt.SerializedEvent) (evt.Event, error)
- func (a *Account) EventUpcasters() []evt.EventUpcaster
- func (a *Account) GetID() evt.EntityID
- func (a *Account) Handle(_ context.Context, command evt.Command) (evt.CommandResult, error)
- func (a *Account) Projectors() []evt.EventProjector
- func (a *Account) SetID(id evt.EntityID)
- func (a *Account) Type() evt.EntityType
- type AccountClosed
- type AccountLabeled
- type AccountOpened
- type AccountRenamed
- type AccountTagged
- type CodecFixtures
- type Command
- type DecodeVector
- type EventInput
- type EventVector
- type FakeDynamo
- func (f *FakeDynamo) BatchGetItem(context.Context, *dynamodb.BatchGetItemInput, ...func(*dynamodb.Options)) (*dynamodb.BatchGetItemOutput, error)
- func (f *FakeDynamo) BatchWriteItem(_ context.Context, params *dynamodb.BatchWriteItemInput, ...) (*dynamodb.BatchWriteItemOutput, error)
- func (f *FakeDynamo) DeleteItem(context.Context, *dynamodb.DeleteItemInput, ...func(*dynamodb.Options)) (*dynamodb.DeleteItemOutput, error)
- func (f *FakeDynamo) ExportTableToPointInTime(context.Context, *dynamodb.ExportTableToPointInTimeInput, ...) (*dynamodb.ExportTableToPointInTimeOutput, error)
- func (f *FakeDynamo) GetItem(_ context.Context, params *dynamodb.GetItemInput, _ ...func(*dynamodb.Options)) (*dynamodb.GetItemOutput, error)
- func (f *FakeDynamo) Items(pk string) []map[string]types.AttributeValue
- func (f *FakeDynamo) PutItem(_ context.Context, params *dynamodb.PutItemInput, _ ...func(*dynamodb.Options)) (*dynamodb.PutItemOutput, error)
- func (f *FakeDynamo) Query(_ context.Context, params *dynamodb.QueryInput, _ ...func(*dynamodb.Options)) (*dynamodb.QueryOutput, error)
- func (f *FakeDynamo) Scan(context.Context, *dynamodb.ScanInput, ...func(*dynamodb.Options)) (*dynamodb.ScanOutput, error)
- func (f *FakeDynamo) TransactWriteItems(_ context.Context, params *dynamodb.TransactWriteItemsInput, ...) (*dynamodb.TransactWriteItemsOutput, error)
- func (f *FakeDynamo) UpdateItem(context.Context, *dynamodb.UpdateItemInput, ...func(*dynamodb.Options)) (*dynamodb.UpdateItemOutput, error)
- type MoneyDeposited
- type MoneyWithdrawn
- type Outcome
- type RawEvent
- type RejectedError
- type Runner
- type Scenario
- type ScenarioExpectation
- type ScenarioFixtures
- type Scenarios
- type SnapshotInput
- type SnapshotVector
- type Step
- type TTLStream
- type TTLVector
- type ViewVector
Constants ¶
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.
const ( CodecFixtureFile = "codec.json" ScenarioFixtureFile = "scenarios.json" )
Fixture file names under compat/fixtures.
const ( WriterGo = "go" WriterRust = "rust" )
Writer names used in scenario steps and recorded as the metadata origin endpoint.
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.
const ( ResultOK = "ok" ResultRejected = "rejected" ResultDuplicate = "duplicate" ResultConflict = "conflict" ResultCompacted = "compacted" ResultUncovered = "uncovered" )
Step results.
const AccountType evt.EntityType = "account"
AccountType is the entity type of the shared account aggregate.
Variables ¶
This section is empty.
Functions ¶
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 FixturePath ¶
FixturePath returns the path of a fixture file.
func MarshalFixture ¶
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 ¶
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 ¶
NewAccount returns an empty account for the given entity ID.
func (*Account) DeserializeEvent ¶
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) Handle ¶
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) 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 ¶
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 ¶
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.
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 (*FakeDynamo) BatchGetItem ¶
func (f *FakeDynamo) BatchGetItem(context.Context, *dynamodb.BatchGetItemInput, ...func(*dynamodb.Options)) (*dynamodb.BatchGetItemOutput, error)
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 ¶
func (f *FakeDynamo) DeleteItem(context.Context, *dynamodb.DeleteItemInput, ...func(*dynamodb.Options)) (*dynamodb.DeleteItemOutput, error)
DeleteItem is not supported.
func (*FakeDynamo) ExportTableToPointInTime ¶
func (f *FakeDynamo) ExportTableToPointInTime( context.Context, *dynamodb.ExportTableToPointInTimeInput, ...func(*dynamodb.Options), ) (*dynamodb.ExportTableToPointInTimeOutput, error)
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 ¶
func (f *FakeDynamo) Scan(context.Context, *dynamodb.ScanInput, ...func(*dynamodb.Options)) (*dynamodb.ScanOutput, error)
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 ¶
func (f *FakeDynamo) UpdateItem(context.Context, *dynamodb.UpdateItemInput, ...func(*dynamodb.Options)) (*dynamodb.UpdateItemOutput, error)
UpdateItem is not supported.
type MoneyDeposited ¶
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.
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.
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 ¶
func (e ScenarioExpectation) ForRun(run string) (ScenarioExpectation, error)
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 ¶
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.
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). |