projection

package
v1.0.0-beta.161 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package projection provides a small contract-validating client for graph mutations. Contracts describe operation intent and expected graph shape; they do not grant ownership or prevent other components from writing.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidContract = errors.New("projection: invalid contract")

ErrInvalidContract identifies a projection contract rejected before use.

Functions

func ValidateContracts 

func ValidateContracts(contracts []Contract) error

ValidateContracts validates a complete, uniquely named contract set.

Types

type AppendMutation 

type AppendMutation struct {
	Contract string
	Group    string
	EntityID string
	Triples  []message.Triple
	Metadata MutationMetadata
}

AppendMutation requests set-valued addition to one declared predicate group.

type AuthoritativeReader 

type AuthoritativeReader interface {
	ReadAuthoritative(context.Context, string) (*graph.ExactEntity, error)
}

AuthoritativeReader reads entity bytes and their same-entry KV revision.

type CommitState 

type CommitState string

CommitState reports what the client can prove about mutation commitment. 

const (
	// CommitNotCommitted proves the mutation did not commit.
	CommitNotCommitted CommitState = "not-committed"
	// CommitUnknown reports that delivery occurred without a valid reply.
	CommitUnknown CommitState = "unknown"
	// CommitVerified reports a valid authoritative mutation response.
	CommitVerified CommitState = "verified"
)

type Contract 

type Contract struct {
	Name            string           `json:"name"`
	MessageType     string           `json:"message_type,omitempty"`
	EntityPattern   string           `json:"entity_pattern"`
	Groups          []PredicateGroup `json:"groups,omitempty"`
	BirthPredicates []string         `json:"birth_predicates,omitempty"`
	IndexingProfile string           `json:"indexing_profile,omitempty"`
}

Contract declares the graph shape emitted by one projection. It validates caller intent; it does not reserve predicates or prevent other writers.

func (Contract) Validate 

func (c Contract) Validate() error

Validate checks one projection contract without consulting runtime state.

type CreateMutation 

type CreateMutation struct {
	Contract string
	Entity   *graph.EntityState
	Triples  []message.Triple
	Metadata MutationMetadata
}

CreateMutation requests strict creation of one entity.

type DeleteMutation 

type DeleteMutation struct {
	EntityID         string
	ExpectedRevision uint64
	Metadata         MutationMetadata
}

DeleteMutation requests revision-fenced deletion of one entity.

type EntityCreator 

type EntityCreator interface {
	Create(context.Context, CreateMutation) (MutationReceipt, error)
}

EntityCreator creates one entity through the canonical mutation port.

type EntityDeleter 

type EntityDeleter interface {
	Delete(context.Context, DeleteMutation) (MutationReceipt, error)
}

EntityDeleter deletes one entity at an expected authority revision.

type MutationClient 

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

MutationClient is an immutable, concurrency-safe graph mutation client.

func NewMutationClient 

func NewMutationClient(cfg MutationClientConfig) (*MutationClient, error)

NewMutationClient validates and copies the complete projection contract set.

func (*MutationClient) Append 

func (c *MutationClient) Append(ctx context.Context, request AppendMutation) (MutationReceipt, error)

Append appends triples in one append-mode predicate group to one entity.

func (*MutationClient) Create 

func (c *MutationClient) Create(ctx context.Context, request CreateMutation) (MutationReceipt, error)

Create atomically creates an entity with its complete initial triples.

func (*MutationClient) Delete 

func (c *MutationClient) Delete(ctx context.Context, request DeleteMutation) (MutationReceipt, error)

Delete conditionally deletes one entity. Callers supply the exact revision they intend to fence; the client does not hide a read or retry.

func (*MutationClient) ReadAuthoritative 

func (c *MutationClient) ReadAuthoritative(ctx context.Context, entityID string) (*graph.ExactEntity, error)

ReadAuthoritative returns one validated entity and its same-entry revision.

func (*MutationClient) Reconcile 

func (c *MutationClient) Reconcile(ctx context.Context, request ReconcileMutation) (MutationReceipt, error)

Reconcile replaces one complete reconcile-mode predicate group.

type MutationClientConfig 

type MutationClientConfig struct {
	NATS      *natsclient.Client
	Contracts []Contract
	Timeout   time.Duration
}

MutationClientConfig configures one immutable contract-validating client.

type MutationError 

type MutationError struct {
	Operation MutationOperation
	Kind      MutationErrorKind
	Code      string
	Class     errs.ErrorClass
	Commit    CommitState
	Detail    map[string]any
	Err       error
}

MutationError preserves operation, classification, and commitment evidence.

func (*MutationError) Error 

func (e *MutationError) Error() string

func (*MutationError) Unwrap 

func (e *MutationError) Unwrap() error

type MutationErrorKind 

type MutationErrorKind string

MutationErrorKind is the stable caller-facing mutation failure category. 

const (
	// MutationInvalid reports a request rejected before mutation.
	MutationInvalid MutationErrorKind = "invalid"
	// MutationNotFound reports a required entity that does not exist.
	MutationNotFound MutationErrorKind = "not-found"
	// MutationConflict reports strict-create or semantic conflict.
	MutationConflict MutationErrorKind = "conflict"
	// MutationRevisionConflict reports a stale expected authority revision.
	MutationRevisionConflict MutationErrorKind = "revision-conflict"
	// MutationUnavailable reports no available mutation responder.
	MutationUnavailable MutationErrorKind = "unavailable"
	// MutationCommitUnknown reports delivery without a valid response.
	MutationCommitUnknown MutationErrorKind = "commit-unknown"
	// MutationInternal reports an unclassified framework failure.
	MutationInternal MutationErrorKind = "internal"
)

type MutationMetadata 

type MutationMetadata struct {
	RequestID string
	TraceID   string
	Source    string
	Timestamp time.Time
}

MutationMetadata carries correlation and triple provenance. Create and Append require RequestID and Source. A caller retrying one logical Create or Append must set Timestamp once and reuse the complete Metadata; regenerating it would change tuple identity. Other fields remain operation-specific.

type MutationOperation 

type MutationOperation string

MutationOperation identifies the client operation that produced a result. 

const (
	// MutationOperationCreate identifies strict entity creation.
	MutationOperationCreate MutationOperation = "create"
	// MutationOperationReconcile identifies predicate-set reconciliation.
	MutationOperationReconcile MutationOperation = "reconcile"
	// MutationOperationAppend identifies set-valued triple addition.
	MutationOperationAppend MutationOperation = "append"
	// MutationOperationDelete identifies revision-fenced entity deletion.
	MutationOperationDelete MutationOperation = "delete"
	// MutationOperationReadAuthoritative identifies an exact authority read.
	MutationOperationReadAuthoritative MutationOperation = "read-authoritative"
)

type MutationReceipt 

type MutationReceipt struct {
	Entity     *graph.EntityState
	KVRevision uint64
	Commit     CommitState
}

MutationReceipt contains the authoritative result and commitment evidence.

type PredicateGroup 

type PredicateGroup struct {
	Name       string    `json:"name"`
	Mode       WriteMode `json:"mode"`
	Predicates []string  `json:"predicates"`
}

PredicateGroup names predicates changed together through one operation.

type PredicateReconciler 

type PredicateReconciler interface {
	Reconcile(context.Context, ReconcileMutation) (MutationReceipt, error)
}

PredicateReconciler reconciles one declared predicate group.

type ReconcileMutation 

type ReconcileMutation struct {
	Contract string
	Group    string
	EntityID string
	Desired  []message.Triple
	Metadata MutationMetadata
}

ReconcileMutation requests replacement of one declared predicate group.

type TripleAppender 

type TripleAppender interface {
	Append(context.Context, AppendMutation) (MutationReceipt, error)
}

TripleAppender appends set-valued triples to an existing entity.

type WriteMode 

type WriteMode string

WriteMode states whether a predicate group is replaced as a complete set or appended as evidence. It is operation intent, not semantic ownership. 

const (
	// ModeReconcile declares complete-set predicate reconciliation.
	ModeReconcile WriteMode = "reconcile"
	// ModeAppend declares set-valued predicate addition.
	ModeAppend WriteMode = "append"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.