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
- func Binds(provider *Provider, version int, fingerprint string) bool
- func Broken(cause error) error
- func CanonicalJson(value delta.JsonValue, ctx context.Context) string
- func Check(validator *Validator, value any, reason ChordErrorReason, ctx context.Context) error
- func CheckAddress(kind string, params *contracts.ParamsData, raw any, ctx context.Context) (contracts.Address, error)
- func IdentityKey(contract *contracts.Contract, key string, principalKey ...string) string
- func PrincipalKey(principal Principal, ctx context.Context, customKey *PrincipalKeyFunction) string
- func SameCause(a, b FailureCause) bool
- type BrokenOpen
- type CheckedArgs
- type CheckedArgsKind
- type CheckedParams
- type ChordError
- func AsChordError(err error, label string) *ChordError
- func ChordErrorFromJson(raw any) (*ChordError, error)
- func Invalid(reason ChordErrorReason, message string, details ...delta.JsonValue) *ChordError
- func IsChordError(err error) (*ChordError, bool)
- func IsChordErrorCode(err error, code ChordErrorCode) (*ChordError, bool)
- func NewChordError(init ChordErrorInit, cause error) *ChordError
- type ChordErrorCode
- type ChordErrorInit
- type ChordErrorReason
- type FailureCause
- type FailureKind
- type PluginError
- type Principal
- type PrincipalKeyFunction
- type Provider
- type SchemaOwner
- type Validator
- type Value
Constants ¶
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 ¶
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 CanonicalJson ¶
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 ¶
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 ¶
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.
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 ¶
CheckedParams is the result of CheckParams: the caller's own params object, and its key.
func CheckParams ¶
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) 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.
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" 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 ¶
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.
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 ¶
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.