data

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package data ports packages/chord/src/next/data: Chord's errors and plugin errors, principals, per-call checks of params and arguments, and how a plugin's open reports a broken configuration.

Index

Constants

View Source
const ProtocolVersion = 1

ProtocolVersion is the version of the error table below on links; adding or moving a code or reason bumps it.

Variables

This section is empty.

Functions

func Binds

func Binds(provider *Provider, version int, fingerprint string) bool

Binds reports whether provider binds a consumer of version with fingerprint: its current version and fingerprint, or a version it accepts with the fingerprint its own history computes (R6, Q10).

func Broken

func Broken(cause error) error

Broken marks an open's failure as broken (bad configuration).

func CanonicalJson

func CanonicalJson(value delta.JsonValue, ctx context.Context) string

CanonicalJson is canonical JSON: sorted object keys (by UTF-16 code unit, as JavaScript's sort), `-0` written as `0`. Counts one walk.

func Check

func Check(validator *Validator, value any, reason ChordErrorReason, ctx context.Context) error

Check checks value (counted); a failure returns `invalid/<reason>` with the first error's JSON Pointer path, as upstream throws it. reason is ReasonArgs, ReasonParams or ReasonHostAddress.

func CheckAddress

func CheckAddress(kind string, params *contracts.ParamsData, raw any, ctx context.Context) (contracts.Address, error)

CheckAddress is an address from a kind's name and params as a hold names it or a `hostAddress` returned it: the params checked against the kind's with one compiled closed-object check (`invalid/host_address` on failure), the key computed. raw is a *delta.JsonObject or a map[string]any.

func IdentityKey

func IdentityKey(contract *contracts.Contract, key string, principalKey ...string) string

IdentityKey is the in-process identity of an object: `name|key|principalKey`, each part escaped; a `local` contract has no principal, so its call passes none (upstream's type refuses one; Go checks nothing, and a principal key passed for a local contract becomes a part of the identity).

func PrincipalKey

func PrincipalKey(principal Principal, ctx context.Context, customKey *PrincipalKeyFunction) string

PrincipalKey is the key of a principal: its canonical JSON, or customKey's result. Cached per principal object; a custom key's cache is owned by the function too, so a live principal never retains a dropped function. customKey nil is upstream's absent argument.

func SameCause

func SameCause(a, b FailureCause) bool

SameCause reports whether two failure causes say the same (a wake compares causes by value): kind, code, reason and message.

Types

type BrokenOpen

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

BrokenOpen marks an open's failure as broken (bad configuration): `return nil, Broken(err)`. Its message is its cause's, and Unwrap returns the cause.

func (*BrokenOpen) Error

func (err *BrokenOpen) Error() string

Error returns the cause's message.

func (*BrokenOpen) Unwrap

func (err *BrokenOpen) Unwrap() error

Unwrap returns the cause.

type CheckedArgs

type CheckedArgs struct {
	Kind CheckedArgsKind
	Args Value
	// Result maps the current result back to the caller's version; method only, nil when absent.
	Result contracts.Mapping
	// Call is the provider's replacement; call only.
	Call contracts.CallFunc
}

CheckedArgs is the result of CheckArgs: a method's arguments in the current shape with the result mapping back to the caller's version (kind "method"; Result nil is upstream's absent `result`), or the old arguments for the provider's own `call` replacement (kind "call"; L4 dispatches it).

func CheckArgs

func CheckArgs(provider *Provider, method string, raw any, boundVersion int, ctx context.Context) (CheckedArgs, error)

CheckArgs checks a call's arguments against the provider's schema for the caller's bound version: three map lookups, one compiled check, at most one direct mapping old -> current (never for current-version calls). A method without arguments gets `null` (its internal and wire form). Unknown method: `invalid/member`; version not accepted or refused: `contract_mismatch`.

type CheckedArgsKind

type CheckedArgsKind string

CheckedArgsKind is the kind of CheckedArgs.

const (
	// CheckedMethod is a method's arguments in the current shape.
	CheckedMethod CheckedArgsKind = "method"
	// CheckedCall is the old arguments for the provider's own `call` replacement.
	CheckedCall CheckedArgsKind = "call"
)

type CheckedParams

type CheckedParams struct {
	Params any
	Key    string
}

CheckedParams is the result of CheckParams: the caller's own params object, and its key.

func CheckParams

func CheckParams(contract *contracts.Contract, raw any, ctx context.Context) (CheckedParams, error)

CheckParams checks raw against the contract's params with one compiled closed-object check (`invalid/params` on failure) and returns the caller's own object with its key: the field values in declared order, each escaped, joined with `|`. raw is a *delta.JsonObject or a map[string]any.

type ChordError

type ChordError struct {
	Code       ChordErrorCode
	Reason     ChordErrorReason
	Message    string
	Details    delta.JsonValue
	HasDetails bool
	Cause      error
}

ChordError is a Chord failure. Cause is upstream's `cause` option; stack and cause never cross a link.

func AsChordError

func AsChordError(err error, label string) *ChordError

AsChordError is err itself when it is a ChordError, otherwise an `unavailable` error naming label, with err as cause.

func ChordErrorFromJson

func ChordErrorFromJson(raw any) (*ChordError, error)

ChordErrorFromJson rebuilds a ChordError from a link. It checks the envelope only: a known code, a reason allowed for it (required for `invalid`), a string message, no other keys. Details is kept by reference. raw is a *delta.JsonObject or a map[string]any.

func Invalid

func Invalid(reason ChordErrorReason, message string, details ...delta.JsonValue) *ChordError

Invalid returns an `invalid` error with the given reason; details is optional.

func IsChordError

func IsChordError(err error) (*ChordError, bool)

IsChordError reports whether err is a ChordError and returns it. It is upstream's `instanceof`: an error that wraps a ChordError (with %w, or as Broken's cause) is not one; AsChordError and OpenFailure read the causes they own.

func IsChordErrorCode

func IsChordErrorCode(err error, code ChordErrorCode) (*ChordError, bool)

IsChordErrorCode is IsChordError with the given code.

func NewChordError

func NewChordError(init ChordErrorInit, cause error) *ChordError

NewChordError creates a ChordError: NewChordError(ChordErrorInit{Code: CodeInvalid, Reason: ReasonArgs, Message: m}, nil).

func (*ChordError) AppendStringify

func (err *ChordError) AppendStringify(dst []byte) ([]byte, error)

AppendStringify appends the wire form's JSON.stringify text, which the stringify encoder splices.

func (*ChordError) Error

func (err *ChordError) Error() string

Error returns the message.

func (*ChordError) MarshalJSON

func (err *ChordError) MarshalJSON() ([]byte, error)

MarshalJSON is JSON.stringify's call of toJSON: the wire form, so a ChordError marshals without stack or cause.

func (*ChordError) ToJSON

func (err *ChordError) ToJSON() *delta.JsonObject

ToJSON is the wire form: code, reason, message, details in that order, an absent reason or details left out.

func (*ChordError) Unwrap

func (err *ChordError) Unwrap() error

Unwrap returns the cause.

type ChordErrorCode

type ChordErrorCode string

ChordErrorCode is one of the codes of ChordErrorReasons.

const (
	CodeInvalid          ChordErrorCode = "invalid"
	CodeContractMismatch ChordErrorCode = "contract_mismatch"
	CodeForbidden        ChordErrorCode = "forbidden"
	CodeGone             ChordErrorCode = "gone"
	CodeNotReady         ChordErrorCode = "not_ready"
	CodeReleased         ChordErrorCode = "released"
	CodeTooLarge         ChordErrorCode = "too_large"
	CodeUnavailable      ChordErrorCode = "unavailable"
	CodeAborted          ChordErrorCode = "aborted"
)

The codes of ChordErrorReasons, as their wire spellings.

func ChordErrorCodes

func ChordErrorCodes() []ChordErrorCode

ChordErrorCodes returns every code in the order of upstream's CHORD_ERROR_REASONS.

type ChordErrorInit

type ChordErrorInit struct {
	Code    ChordErrorCode
	Reason  ChordErrorReason
	Message string
	// Details is the JSON details; HasDetails distinguishes an absent details from a JSON null.
	Details    delta.JsonValue
	HasDetails bool
}

ChordErrorInit is the wire form of a ChordError and its constructor argument. Upstream's tagged union makes a wrong code/reason pairing a type error; Go checks the pairing in ChordErrorFromJson only, as upstream's runtime does.

type ChordErrorReason

type ChordErrorReason string

ChordErrorReason is a reason a code may carry; the empty reason is upstream's undefined.

const (
	ReasonArgs          ChordErrorReason = "args"
	ReasonParams        ChordErrorReason = "params"
	ReasonMember        ChordErrorReason = "member"
	ReasonHostAddress   ChordErrorReason = "host_address"
	ReasonReentrant     ChordErrorReason = "reentrant"
	ReasonReadAfterBulk ChordErrorReason = "read_after_bulk"
	ReasonCycle         ChordErrorReason = "cycle"
	ReasonUpdating      ChordErrorReason = "updating"
	ReasonRevoked       ChordErrorReason = "revoked"
	ReasonEnded         ChordErrorReason = "ended"
	ReasonClosed        ChordErrorReason = "closed"
	ReasonSettled       ChordErrorReason = "settled"
	ReasonVersion       ChordErrorReason = "version"
	ReasonDiscarded     ChordErrorReason = "discarded"
	ReasonPart          ChordErrorReason = "part"
	ReasonLocked        ChordErrorReason = "locked"
	ReasonParkTimeout   ChordErrorReason = "park_timeout"
	ReasonBusy          ChordErrorReason = "busy"
	ReasonStorageFailed ChordErrorReason = "storage_failed"
	ReasonUndeclared    ChordErrorReason = "undeclared"
)

The reasons of ChordErrorReasons, as their wire spellings.

func ChordErrorReasons

func ChordErrorReasons(code ChordErrorCode) ([]ChordErrorReason, bool)

ChordErrorReasons is upstream's CHORD_ERROR_REASONS: the reasons a code may carry. `invalid` requires a reason; every other code may omit it. The second result reports whether code is known.

type FailureCause

type FailureCause struct {
	Kind  FailureKind
	Error *ChordError
}

FailureCause is why an object, or a request, is failed.

func OpenFailure

func OpenFailure(thrown error, label string) FailureCause

OpenFailure is the cause of an error returned by an open: broken when it came from Broken, transient otherwise.

func WaitingFor

func WaitingFor(blocker string, err *ChordError) FailureCause

WaitingFor is the `waiting` cause of a dependent parked on blocker, which failed with err: `unavailable`, its message always "waiting for <blocker>: <root cause>" (the root found through any "waiting for …: " of err's message), so a ring of waiting attempts passing causes round reaches the same message after one round; within 500 characters, the label clipped first, the root only past its share. err is its cause.

type FailureKind

type FailureKind string

FailureKind is the kind of a FailureCause, from the failing stage, never from the error code.

const (
	FailureTransient FailureKind = "transient"
	FailureBroken    FailureKind = "broken"
	FailureWaiting   FailureKind = "waiting"
)

The kinds of FailureCause: transient (the object's own effect failed: retry later), broken (its own code, a cycle or authority: retry by hand) or waiting (not its fault: no provider, no fitting version, a dependency that failed; woken by an event).

type PluginError

type PluginError struct {
	Code       string
	Message    string
	Details    delta.JsonValue
	HasDetails bool
}

PluginError is an error a plugin returns for its callers: its own Code, a message and JSON Details. Only these cross a link (never a stack or a cause); a consumer returns it as a PluginError.

func NewPluginError

func NewPluginError(code, message string, details ...delta.JsonValue) *PluginError

NewPluginError creates a PluginError; details is optional.

func (*PluginError) Error

func (err *PluginError) Error() string

Error returns the message.

type Principal

type Principal = *delta.JsonObject

Principal is an app's principal: plain JSON with a `kind`. Chord never persists it. It is a pointer so that a principal has the identity upstream's per-object cache is keyed by.

type PrincipalKeyFunction

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

PrincipalKeyFunction is an app's own principal key function; it must be the same function on every host.

Go forced difference: a Go func value has no identity to key a cache by (two closures of one literal compare equal by code pointer), so the function is held in a struct whose pointer is its identity and which owns the cache of the keys it computed. A live principal therefore never retains a dropped function, as upstream's WeakMap-of-WeakMaps guarantees, because the function's cache lives in the function.

func NewPrincipalKeyFunction

func NewPrincipalKeyFunction(key func(Principal) string) *PrincipalKeyFunction

NewPrincipalKeyFunction wraps an app's key function; the result is the function's identity.

type Provider

type Provider struct {
	Contract *contracts.Contract
	Accepted []contracts.AcceptedVersion
	Accepts  contracts.AcceptsTable
	// contains filtered or unexported fields
}

Provider is a provider's binding of a contract with the older versions it accepts and their mappings (the table as checked, for the state mappings of an older consumer's binding).

func BindProvider

func BindProvider(contract *contracts.Contract, accepts contracts.AcceptsTable) (*Provider, error)

BindProvider binds a contract and the app's accepts table (validated once, kept as it is) into a provider. Builds the dispatch table: accepted version -> method -> schema and mapping; nothing is compiled yet.

type SchemaOwner

type SchemaOwner interface {
	*contracts.Snapshot | *contracts.ParamsData
}

SchemaOwner is a Chord-owned record holding a schema: a snapshot, or a contract's params.

type Validator

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

Validator is the compiled check of one schema: pi-schema's validator.

func ValidatorFor

func ValidatorFor[O SchemaOwner](owner O, ctx context.Context) (*Validator, error)

ValidatorFor is the validator of an owner's schema, compiled on first use (counted) and cached weakly by the owner: the owner's collection evicts it. A schema pi-schema cannot compile is an error.

func (*Validator) Check

func (validator *Validator) Check(value any) (bool, error)

Check reports whether value matches the schema. The error is the one pi-schema raises where its `check` throws: a part of the schema compiled on first use that is malformed or names nothing (`$dynamicRef`).

type Value

type Value = any

Value is JSON plus byte leaves: nil, bool, float64, string, []byte, []any, *delta.JsonObject. Same-host values are plain data and immutable once handed over, by convention.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL