Add D&D enemy event artifact contract
This commit is contained in:
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "notarius.dnd.enemy_events",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["events"],
|
||||
"properties": {
|
||||
"events": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["name", "kind", "source_refs"],
|
||||
"properties": {
|
||||
"name": {"type": "string", "minLength": 1},
|
||||
"kind": {"type": "string", "enum": ["engaged", "killed", "fled", "captured", "incapacitated"]},
|
||||
"source_refs": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["source_id", "start_unit_id", "end_unit_id"],
|
||||
"properties": {
|
||||
"source_id": {"type": "string", "minLength": 1},
|
||||
"start_unit_id": {"type": "integer", "minimum": 1},
|
||||
"end_unit_id": {"type": "integer", "minimum": 1}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
182
internal/modules/dnd/codec/enemyevents/codec.go
Normal file
182
internal/modules/dnd/codec/enemyevents/codec.go
Normal file
@@ -0,0 +1,182 @@
|
||||
// Package enemyevents encodes durable D&D enemy-event artifacts.
|
||||
package enemyevents
|
||||
|
||||
import (
|
||||
"embed"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/candidatejson"
|
||||
)
|
||||
|
||||
const (
|
||||
SchemaID = "notarius.dnd.enemy_events"
|
||||
SchemaName = "notarius_dnd_enemy_events_v1"
|
||||
SchemaVersion = "v1"
|
||||
MediaType = "application/json"
|
||||
)
|
||||
|
||||
//go:embed assets/schemas/dnd_enemy_events.v1.json
|
||||
var schemaAssets embed.FS
|
||||
|
||||
var _ contracts.ArtifactCodec[dnd.EnemyEventList] = (*Codec)(nil)
|
||||
|
||||
type Codec struct{}
|
||||
|
||||
func New() *Codec { return &Codec{} }
|
||||
|
||||
func (c *Codec) Kind() contracts.ArtifactKind { return dnd.EnemyEventListKind }
|
||||
|
||||
func (c *Codec) Schema() contracts.ArtifactSchema {
|
||||
raw, err := schemaAssets.ReadFile("assets/schemas/dnd_enemy_events.v1.json")
|
||||
if err != nil {
|
||||
return contracts.ArtifactSchema{}
|
||||
}
|
||||
return contracts.ArtifactSchema{
|
||||
ID: SchemaID,
|
||||
Name: SchemaName,
|
||||
Version: SchemaVersion,
|
||||
JSONSchema: append([]byte(nil), raw...),
|
||||
}
|
||||
}
|
||||
|
||||
func (c *Codec) MediaType() string { return MediaType }
|
||||
|
||||
func (c *Codec) Metadata(value dnd.EnemyEventList) map[string]any {
|
||||
return map[string]any{"event_count": len(value.Events)}
|
||||
}
|
||||
|
||||
func (c *Codec) Encode(value dnd.EnemyEventList) ([]byte, error) {
|
||||
if err := validateRequiredValueFields(value); err != nil {
|
||||
return nil, fmt.Errorf("encode dnd enemy event list: %w", err)
|
||||
}
|
||||
return c.EncodeCandidate(value)
|
||||
}
|
||||
|
||||
// EncodeCandidate provides the durable representation before semantic
|
||||
// validators have approved a value.
|
||||
func (c *Codec) EncodeCandidate(value dnd.EnemyEventList) ([]byte, error) {
|
||||
return candidatejson.EncodeCandidate("dnd enemy event list", cloneList(value))
|
||||
}
|
||||
|
||||
func (c *Codec) Decode(content []byte) (dnd.EnemyEventList, error) {
|
||||
value, err := c.DecodeCandidate(content)
|
||||
if err != nil {
|
||||
return dnd.EnemyEventList{}, err
|
||||
}
|
||||
if err := validateRequiredJSONFields(content); err != nil {
|
||||
return dnd.EnemyEventList{}, fmt.Errorf("decode dnd enemy event list: %w", err)
|
||||
}
|
||||
return value, nil
|
||||
}
|
||||
|
||||
// DecodeCandidate reads one strict durable JSON value before semantic
|
||||
// validators have approved it.
|
||||
func (c *Codec) DecodeCandidate(content []byte) (dnd.EnemyEventList, error) {
|
||||
value, err := candidatejson.DecodeCandidate[dnd.EnemyEventList]("dnd enemy event list", content)
|
||||
if err != nil {
|
||||
return dnd.EnemyEventList{}, err
|
||||
}
|
||||
return cloneList(value), nil
|
||||
}
|
||||
|
||||
func validateRequiredValueFields(value dnd.EnemyEventList) error {
|
||||
if value.Events == nil {
|
||||
return fmt.Errorf("events must be present")
|
||||
}
|
||||
for index, event := range value.Events {
|
||||
if event.SourceRefs == nil {
|
||||
return fmt.Errorf("events[%d].source_refs must be present", index)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func validateRequiredJSONFields(content []byte) error {
|
||||
var root map[string]json.RawMessage
|
||||
if err := json.Unmarshal(content, &root); err != nil || root == nil {
|
||||
return fmt.Errorf("must be a JSON object")
|
||||
}
|
||||
events, err := requiredArray(root, "events", "")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for eventIndex, rawEvent := range events {
|
||||
path := fmt.Sprintf("events[%d]", eventIndex)
|
||||
var event map[string]json.RawMessage
|
||||
if err := json.Unmarshal(rawEvent, &event); err != nil || event == nil {
|
||||
return fmt.Errorf("%s must be an object", path)
|
||||
}
|
||||
for _, field := range []string{"name", "kind"} {
|
||||
if err := requireField(event, field, path); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
refs, err := requiredArray(event, "source_refs", path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for refIndex, rawRef := range refs {
|
||||
refPath := fmt.Sprintf("%s.source_refs[%d]", path, refIndex)
|
||||
var ref map[string]json.RawMessage
|
||||
if err := json.Unmarshal(rawRef, &ref); err != nil || ref == nil {
|
||||
return fmt.Errorf("%s must be an object", refPath)
|
||||
}
|
||||
for _, field := range []string{"source_id", "start_unit_id", "end_unit_id"} {
|
||||
if err := requireField(ref, field, refPath); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func requiredArray(object map[string]json.RawMessage, field, path string) ([]json.RawMessage, error) {
|
||||
raw, err := requiredField(object, field, path)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var values []json.RawMessage
|
||||
if err := json.Unmarshal(raw, &values); err != nil {
|
||||
return nil, fmt.Errorf("%s must be an array", fieldPath(path, field))
|
||||
}
|
||||
return values, nil
|
||||
}
|
||||
|
||||
func requireField(object map[string]json.RawMessage, field, path string) error {
|
||||
_, err := requiredField(object, field, path)
|
||||
return err
|
||||
}
|
||||
|
||||
func requiredField(object map[string]json.RawMessage, field, path string) (json.RawMessage, error) {
|
||||
raw, ok := object[field]
|
||||
if !ok || string(raw) == "null" {
|
||||
return nil, fmt.Errorf("%s must be present", fieldPath(path, field))
|
||||
}
|
||||
return raw, nil
|
||||
}
|
||||
|
||||
func fieldPath(path, field string) string {
|
||||
if path == "" {
|
||||
return field
|
||||
}
|
||||
return path + "." + field
|
||||
}
|
||||
|
||||
func cloneList(value dnd.EnemyEventList) dnd.EnemyEventList {
|
||||
if value.Events == nil {
|
||||
return dnd.EnemyEventList{}
|
||||
}
|
||||
cloned := dnd.EnemyEventList{Events: make([]dnd.EnemyEvent, len(value.Events))}
|
||||
for index, event := range value.Events {
|
||||
cloned.Events[index] = event
|
||||
if event.SourceRefs != nil {
|
||||
cloned.Events[index].SourceRefs = append([]source.SourceRef(nil), event.SourceRefs...)
|
||||
}
|
||||
}
|
||||
return cloned
|
||||
}
|
||||
99
internal/modules/dnd/codec/enemyevents/codec_test.go
Normal file
99
internal/modules/dnd/codec/enemyevents/codec_test.go
Normal file
@@ -0,0 +1,99 @@
|
||||
package enemyevents
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
||||
)
|
||||
|
||||
func validList() dnd.EnemyEventList {
|
||||
return dnd.EnemyEventList{Events: []dnd.EnemyEvent{
|
||||
{Name: "Ashfang", Kind: dnd.EnemyEventKindEngaged, SourceRefs: refs(1, 2)},
|
||||
{Name: "Ashfang", Kind: dnd.EnemyEventKindFled, SourceRefs: refs(5, 6)},
|
||||
}}
|
||||
}
|
||||
|
||||
func refs(start, end int) []source.SourceRef {
|
||||
return []source.SourceRef{{SourceID: "session", StartUnitID: start, EndUnitID: end}}
|
||||
}
|
||||
|
||||
func TestCodecRoundTripAndIdentity(t *testing.T) {
|
||||
codec := New()
|
||||
value := validList()
|
||||
content, err := codec.Encode(value)
|
||||
if err != nil {
|
||||
t.Fatalf("Encode() error = %v", err)
|
||||
}
|
||||
decoded, err := codec.Decode(content)
|
||||
if err != nil || !reflect.DeepEqual(decoded, value) {
|
||||
t.Fatalf("Decode() = %#v, %v; want %#v", decoded, err, value)
|
||||
}
|
||||
|
||||
schema := codec.Schema()
|
||||
if codec.Kind() != dnd.EnemyEventListKind || codec.MediaType() != MediaType || schema.ID != SchemaID || schema.Name != SchemaName || schema.Version != SchemaVersion || !json.Valid(schema.JSONSchema) {
|
||||
t.Fatalf("codec identity/schema = %q/%q %#v", codec.Kind(), codec.MediaType(), schema)
|
||||
}
|
||||
registry := pipeline.NewArtifactCodecRegistry()
|
||||
if err := pipeline.RegisterArtifactCodec(registry, codec); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
spec, ok := registry.Spec(dnd.EnemyEventListKind)
|
||||
if !ok || spec.SchemaDigest != contracts.DigestArtifactSchema(schema) {
|
||||
t.Fatalf("registered spec = %#v, %t", spec, ok)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCodecRejectsStrictJSONAndMissingRequiredFields(t *testing.T) {
|
||||
validJSON := `{"events":[{"name":"Ashfang","kind":"engaged","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`
|
||||
tests := []struct {
|
||||
name, raw, want string
|
||||
}{
|
||||
{"invalid JSON", `{`, "decode dnd enemy event list"},
|
||||
{"unknown root field", `{"events":[],"unexpected":true}`, "unknown field"},
|
||||
{"unknown event field", strings.Replace(validJSON, `"kind":"engaged"`, `"kind":"engaged","unexpected":true`, 1), "unknown field"},
|
||||
{"missing events", `{}`, "events must be present"},
|
||||
{"missing name", strings.Replace(validJSON, `"name":"Ashfang",`, "", 1), "events[0].name must be present"},
|
||||
{"missing kind", strings.Replace(validJSON, `"kind":"engaged",`, "", 1), "events[0].kind must be present"},
|
||||
{"missing refs", strings.Replace(validJSON, `,"source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]`, "", 1), "events[0].source_refs must be present"},
|
||||
{"missing source ID", strings.Replace(validJSON, `"source_id":"session",`, "", 1), "source_refs[0].source_id must be present"},
|
||||
{"trailing JSON", `{"events":[]} {}`, "multiple JSON values"},
|
||||
}
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
if _, err := New().Decode([]byte(test.raw)); err == nil || !strings.Contains(err.Error(), test.want) {
|
||||
t.Fatalf("Decode() error = %v, want %q", err, test.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestCodecDefensivelyOwnsValuesAndDefersSemanticValidation(t *testing.T) {
|
||||
codec := New()
|
||||
candidate := dnd.EnemyEventList{Events: []dnd.EnemyEvent{{
|
||||
Name: " ", Kind: "unsupported", SourceRefs: []source.SourceRef{{SourceID: "", StartUnitID: 0, EndUnitID: -1}},
|
||||
}}}
|
||||
content, err := codec.EncodeCandidate(candidate)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
decoded, err := codec.Decode(content)
|
||||
if err != nil || !reflect.DeepEqual(decoded, candidate) {
|
||||
t.Fatalf("Decode() = %#v, %v; want semantic candidate preservation", decoded, err)
|
||||
}
|
||||
decoded.Events[0].SourceRefs[0].SourceID = "changed"
|
||||
if candidate.Events[0].SourceRefs[0].SourceID != "" {
|
||||
t.Fatal("Decode() retained caller-owned source references")
|
||||
}
|
||||
|
||||
first := codec.Schema()
|
||||
first.JSONSchema[0] = '['
|
||||
if second := codec.Schema(); !json.Valid(second.JSONSchema) || second.JSONSchema[0] == '[' {
|
||||
t.Fatal("Schema() returned shared bytes")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user