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
- Variables
- func ValidateContracts(contracts []Contract) error
- type AppendMutation
- type CommitState
- type Contract
- type CreateMutation
- type DeleteMutation
- type MutationClient
- func (c *MutationClient) Append(ctx context.Context, request AppendMutation) (MutationReceipt, error)
- func (c *MutationClient) Create(ctx context.Context, request CreateMutation) (MutationReceipt, error)
- func (c *MutationClient) Delete(ctx context.Context, request DeleteMutation) (MutationReceipt, error)
- func (c *MutationClient) ReadAuthoritative(ctx context.Context, entityID string) (*graph.ExactEntity, error)
- func (c *MutationClient) Reconcile(ctx context.Context, request ReconcileMutation) (MutationReceipt, error)
- type MutationClientConfig
- type MutationError
- type MutationErrorKind
- type MutationMetadata
- type MutationOperation
- type MutationReceipt
- type PredicateGroup
- type PredicateReconciler
- type ReconcileMutation
- type WriteMode
Constants ¶
const ( // ModeReconcile declares complete-set predicate reconciliation. ModeReconcile = contract.ModeReconcile // ModeAppend declares set-valued predicate addition. ModeAppend = contract.ModeAppend )
Variables ¶
var ErrInvalidContract = contract.ErrInvalidContract
ErrInvalidContract identifies a projection contract rejected before use.
Functions ¶
func ValidateContracts ¶
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 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 the mutation may have committed: it was delivered, and neither // its reply nor its absence proves the outcome. CommitUnknown CommitState = "unknown" // CommitVerified reports a valid authoritative mutation response. CommitVerified CommitState = "verified" )
type Contract ¶
Contract declares the graph shape emitted by one projection. It validates caller intent; it does not reserve predicates or prevent other writers.
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 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.
A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.
func (*MutationClient) Create ¶
func (c *MutationClient) Create(ctx context.Context, request CreateMutation) (MutationReceipt, error)
Create atomically creates an entity with its complete initial triples.
A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.
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.
A zero ExpectedRevision is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.
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.
A read writes nothing, so every failure is not committed, with operation read-authoritative.
func (*MutationClient) Reconcile ¶
func (c *MutationClient) Reconcile(ctx context.Context, request ReconcileMutation) (MutationReceipt, error)
Reconcile replaces one complete reconcile-mode predicate group, at the request's ExpectedRevision or, when that is zero, at the revision the client reads.
It reads the entity first. A failed read sends no mutation and is not committed, with operation read-authoritative; a stored entity outside the contract is refused as MutationInvalid. A request that is incomplete or outside the contract is refused before it is sent: Kind MutationInvalid, not committed. Any other failure follows ClassifyMutationError. A nil error means the commit is verified.
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 ClassifyMutationError ¶
func ClassifyMutationError(operation MutationOperation, err error) *MutationError
ClassifyMutationError maps the error of one graph mutation request to the commit state it proves, and returns nil for a nil error. It is the one mapping every MutationClient write uses.
The error is not committed in two cases. Its chain holds a classified reply whose code graph-ingest sends only before it writes (invalid request, structural invalid, message type unregistered, entity ID invalid, entity ID authority invalid, revision mismatch, entity exists, entity not found, graph state reset required): the error keeps that reply's class, code and a copy of its detail. Or the request was not delivered, because no responder took it, natsclient refused it before sending (ErrNotConnected), or the caller's context ended before it was sent: Kind MutationUnavailable, class transient.
Every other error, a classified reply with any other code included, is commit-unknown and fatal, so it is never retried: a write that may have committed could apply twice.
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" // write, the request was not delivered: no responder took it, or the caller's context ended // before it was sent. For a read (operation read-authoritative), the request may have been // delivered, but a read stores nothing. MutationUnavailable MutationErrorKind = "unavailable" // MutationCommitUnknown reports a mutation that may have committed (CommitUnknown). MutationCommitUnknown MutationErrorKind = "commit-unknown" // MutationInternal reports an unclassified framework failure. MutationInternal MutationErrorKind = "internal" )
type MutationMetadata ¶
MutationMetadata carries correlation and triple provenance. Create and Append require RequestID and Source; Reconcile requires Source and sends it as the request's source. Every statement of a Create, Append or Reconcile needs a Timestamp, its own or this one: the client never reads the clock. 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
}
MutationReceipt contains the authoritative result of a mutation that committed. A method that fails returns a zero receipt, and its *MutationError's Commit reports what is proven.
type PredicateGroup ¶
type PredicateGroup = contract.PredicateGroup
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. It is the one type both ends of the rule-pack binding name: service.ProjectionBinder receives it and the rule processor that binds the pack calls it, so neither names *MutationClient.
type ReconcileMutation ¶
type ReconcileMutation struct {
Contract string
Group string
EntityID string
// ExpectedRevision is the entity's revision the caller read. graph-ingest applies the
// reconcile only while the entity is still at that revision, and otherwise refuses it with a
// revision conflict and changes nothing. Zero means the caller names no revision: the client
// fences at the revision of its own read, so a write between the caller's read and the
// client's goes undetected.
ExpectedRevision uint64
Desired []message.Triple
Metadata MutationMetadata
}
ReconcileMutation requests replacement of one declared predicate group.