complyapi

Go library providing event contract types for the ComplyTime ecosystem.

Events use CloudEvents v1.0 envelopes with JSON-encoded payloads. Go types in events/events.go are the source of truth for event contracts; the AsyncAPI 3.0 spec and JSON Schema files are generated from those types via go generate. Do not edit the generated files manually.

Installation

go get github.com/complytime/complyapi

Usage

package main

import (
	"fmt"
	"log"

	"github.com/complytime/complyapi/events"
)

func main() {
	data := events.EvidenceIngestedData{
		ContentDigest: "sha256:abc123...",
		ArtifactType:  "application/vnd.gemara.evaluation-log+json",
		StorageRef:    "s3://evidence-bucket/my-app-v1/evaluation-log.json",
		SubjectID:     "my-app-v1",
	}

	e, err := events.NewEvidenceIngestedEvent("my-service", "my-app-v1", data)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(e.Type()) // dev.complytime.evidence.ingested
}

Event Types

Type	Constant	Description
dev.complytime.evidence.ingested	events.TypeEvidenceIngested	Evidence accepted for processing, before validation
dev.complytime.evidence.sealed	events.TypeEvidenceSealed	Evidence validated and sealed into a unit of work
dev.complytime.evidence.quarantined	events.TypeEvidenceQuarantined	Evidence failed validation and was quarantined

Correlation

Events do not carry a dedicated correlation attribute.

• Join an artifact's lifecycle events (ingested → sealed|quarantined) on the shared contentDigest. Caveat: a quarantined event whose reason is a content-digest mismatch is the one case where the digest is itself in doubt.

• Trace across services using the CloudEvents Distributed Tracing extension (traceparent/tracestate, W3C Trace Context). This is the observability plane, set and propagated by the producer's tracing SDK, not by this library.

Payload Examples

Example CloudEvents JSON payloads are in api/events/examples/:

File	Description
evidence-ingested.json	Ingested outcome; all data fields including storageRef
evidence-sealed.json	Sealed outcome after successful validation
evidence-quarantined.json	Quarantined outcome after failed validation, with reason

These examples conform to the JSON Schema and AsyncAPI spec. They are hand-maintained reference payloads; the generated schemas remain the source of truth for validation.

Development

Prerequisites

• Go (version per go.mod)
• Task (task runner)
• golangci-lint
• Node.js with npx (required by task asyncapi-lint; first run downloads the AsyncAPI CLI from npm)

After modifying Go structs in events/events.go, regenerate derived artifacts:

task generate

This runs go generate ./events/... which rebuilds api/events/asyncapi.yaml and the JSON Schema files in api/events/schemas/.

To validate the generated AsyncAPI spec:

task asyncapi-lint

To run all checks (lint, vet, test, asyncapi validation):

task check

Adding a new event type

1. Define a new *Data struct in events/events.go with a sentinel blank field carrying the asyncapi tag. The tag is a comma-separated list of key:value pairs. Values must not contain commas (the parser splits on commas, and a comma inside a value silently truncates it). Use semicolons for natural pauses. Recognised keys:

   Key	Required	Format	Description
   channel	yes	NATS subject with {param} placeholders	Channel address
   param	no	name=description (repeatable)	Channel parameter
   stream	yes	Upper-case stream name	NATS JetStream stream
   type	yes	Reverse-DNS CloudEvents type	CloudEvents type attribute
   send	yes	Free text (no commas)	Send operation summary
   receive	yes	Free text (no commas)	Receive operation summary
   description	no	Free text (no commas)	Channel description

   Example sentinel field:

   _ struct{} `asyncapi:"channel:complyapi.widget.created.{ownerId},param:ownerId=The widget owner,stream:WIDGETS,type:dev.complytime.widget.created,send:Published when a widget is created,receive:Consume widget-created events,description:Widget creation pipeline"`

2. Add asyncapi-field:"description:..." tags on each struct field for schema descriptions.

3. Run task generate to regenerate all derived artifacts.

4. Add a constructor function (e.g., NewYourEventEvent()) following the existing pattern.

Evolving an event contract

Before changing an existing event's payload, read the Event Versioning Strategy. It defines which field to bump for additive versus breaking changes (CloudEvents type and AsyncAPI info.version), and why the NATS subject stays stable so subscribers never re-subscribe.

License

Apache-2.0