Eve library

Version negotiation

Evidence

Revision 1

On this page

One carrier per transport, and the four transports that have no counterparty to negotiate with.

Generated from libs/oshun/workbench-kit/src/negotiation.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S1.11. Do not edit by hand.

Summary#

  • src/negotiation.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/negotiation contract S1.11

Exports#

Symbol Kind Summary
bindVersion function Derive the binding from a negotiated version.
CapabilitySupport interface —
CARRIER_MECHANISMS enumeration —
CarrierMechanism type —
discoveryDocument function Build the discovery document, for an AUTHENTICATED caller only.
DiscoveryDocument interface —
DiscoveryEntry interface —
negotiate function Choose a version, or refuse with a code that says which way the mismatch went.
NEGOTIATION_REASONS enumeration —
NEGOTIATION_VIOLATION_KINDS enumeration —
NegotiationOutcome type —
NegotiationReason type —
NegotiationRequest interface —
NegotiationViolation interface —
NegotiationViolationKind type —
REFUSAL_CODES enumeration —
RefusalCode type —
SYNCHRONOUS_TRANSPORTS enumeration The transports with a live counterparty at the moment the version is chosen.
Transport type —
TRANSPORTS enumeration —
validateBinding function S1.11.f — the negotiated version must reach every downstream key.
validateCarriers function —
validateDiscovery function —
validateSupport function —
VERSION_CARRIERS constant The carriers, one per transport.
VersionBinding interface —
VersionCarrier interface —
VersionDeprecation interface —

Shapes#

bindVersion#

Derive the binding from a negotiated version.

ts
bindVersion(capability: CapabilityId, version: number): VersionBinding

CapabilitySupport#

Field Type Required Notes
capability CapabilityId required —
supported readonly number[] required Exact versions this deployment implements, ascending. Never a range.
defaultVersion number required What a client that declared nothing gets, when the carrier allows that.
preference readonly number[] required The server's own preference order, most preferred first.
enabled boolean required False when the deployment has switched the capability off entirely.

CARRIER_MECHANISMS#

Values: media-type-parameter, header, envelope-field, manifest-field, handshake, compiled-constant

CarrierMechanism#

ts
(typeof CARRIER_MECHANISMS)[number];

discoveryDocument#

Build the discovery document, for an AUTHENTICATED caller only.

ts
discoveryDocument(entries: readonly DiscoveryEntry[], caller: { readonly authenticated: boolean; readonly subject: string }): ParseResult<DiscoveryDocument>

DiscoveryDocument#

Field Type Required Notes
generatedFor string required —
entries readonly DiscoveryEntry[] — DiscoveryEntry required —

DiscoveryEntry#

Field Type Required Notes
capability CapabilityId required —
owner string required —
lifecycle Lifecycle required —
supported readonly number[] required —
defaultVersion number required —
deprecations readonly VersionDeprecation[] — VersionDeprecation required —
docsUrl string required —
enabled boolean required —

negotiate#

Choose a version, or refuse with a code that says which way the mismatch went.

ts
negotiate(request: NegotiationRequest, support: CapabilitySupport): NegotiationOutcome

NEGOTIATION_REASONS#

Values: exact-single-offer, server-preference, highest-common, server-default

NEGOTIATION_VIOLATION_KINDS#

Values: duplicate-carrier-for-transport, transport-without-carrier, asynchronous-transport-claims-negotiation, carrier-without-example, empty-supported-set, unsorted-supported-set, duplicate-supported-version, default-version-not-supported, preference-outside-supported, deprecated-version-without-replacement, sunset-version-still-supported, discovery-entry-without-owner, discovery-entry-without-docs, discovery-entry-hides-a-served-version, cache-key-without-version, idempotency-key-without-version, binding-without-audit-field, binding-without-telemetry-attribute, binding-version-not-negotiated

NegotiationOutcome#

ts
| { readonly outcome: 'negotiated'; readonly version: number; readonly reason: NegotiationReason; readonly departedFrom: number | null; readonly direction: 'upgrade' | 'downgrade' | null; }
| { readonly outcome: 'refused'; readonly code: RefusalCode; readonly supported: readonly number[]; readonly detail: string; }
| { readonly outcome: 'unavailable'; readonly capability: CapabilityId; readonly reason: string }

NegotiationReason#

ts
(typeof NEGOTIATION_REASONS)[number];

NegotiationRequest#

Field Type Required Notes
offers readonly number[] required The versions the client offered, in ITS preference order. An empty array means the client declared nothing, which is a different case from offering a version nobody supports.
transport Transport required —
unparseableOffers readonly string[] optional Offered values that were carried but are not versions at all.

NegotiationViolation#

Field Type Required Notes
kind NegotiationViolationKind required —
subject string required —
detail string required —

NegotiationViolationKind#

ts
(typeof NEGOTIATION_VIOLATION_KINDS)[number];

REFUSAL_CODES#

Values: validation.version_missing, validation.version_too_old, validation.version_too_new, validation.version_unsupported, validation.version_unknown

RefusalCode#

ts
(typeof REFUSAL_CODES)[number];

SYNCHRONOUS_TRANSPORTS#

The transports with a live counterparty at the moment the version is chosen.

Values: http, bridge

Transport#

ts
(typeof TRANSPORTS)[number];

TRANSPORTS#

Values: http, event, job, bundle, bridge, generated-client

validateBinding#

S1.11.f — the negotiated version must reach every downstream key.

ts
validateBinding(binding: VersionBinding, negotiatedVersion: number): readonly NegotiationViolation[]

validateCarriers#

ts
validateCarriers(carriers: readonly VersionCarrier[]): readonly NegotiationViolation[]

validateDiscovery#

ts
validateDiscovery(entries: readonly DiscoveryEntry[], now: Instant): readonly NegotiationViolation[]

validateSupport#

ts
validateSupport(support: CapabilitySupport): readonly NegotiationViolation[]

VERSION_CARRIERS#

The carriers, one per transport.

VersionBinding#

Field Type Required Notes
version number required —
validatorId string required —
serializerId string required —
cacheKeyPrefix string required —
idempotencyKeyPrefix string required —
auditField string required —
telemetryAttribute string required —

VersionCarrier#

Field Type Required Notes
transport Transport required —
mechanism CarrierMechanism required —
name string required The header, field or parameter name. One name, one place.
required boolean required Whether a message with no version at all is refused.
negotiable boolean required Whether the receiving side may answer with a different version.
example string required —

VersionDeprecation#

Field Type Required Notes
version number required —
deprecatedIn number required —
sunsetOn Instant required The date after which the version stops being served. Never null.
replacedBy number required —

Valid examples#

binding/a-derived-binding-carries-the-version-everywhere#

the positive case, and the one the propagation test builds on

json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}

Invalid examples#

binding/a-cache-key-shared-across-versions#

it serves a v1 body to a v2 client, and it looks like a working system until somebody upgrades

Must produce: cache-key-without-version

json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
binding/an-audit-row-that-does-not-name-the-contract#

an audit row that does not say which contract was in force cannot be replayed

Must produce: binding-without-audit-field

json
{
  "auditField": "",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
binding/an-idempotency-key-shared-across-versions#

a retried command at a new version deduped against the old one returns the OLD shape with a 200, which is the failure a client is least likely to detect

Must produce: idempotency-key-without-version

json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}

3 of 5 refused case(s) shown. The full corpus is committed at evidence/v1-workbenches/workbench-kit-negotiation-fixtures.json and is what the gate runs.

Authorization and scope#

Not applicable: nothing on this page carries an actor, a grant, a scope or a tenant, so authorization is decided entirely by the caller.

Idempotency and concurrency#

Symbol Type Notes
VersionBinding.idempotencyKeyPrefix string —

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
NEGOTIATION_VIOLATION_KINDS enumeration —
NegotiationOutcome type —
NegotiationViolationKind type —
REFUSAL_CODES enumeration —
RefusalCode type —

Compatibility#

Symbol Type Notes
bindVersion function Derive the binding from a negotiated version.
CapabilitySupport.defaultVersion number What a client that declared nothing gets, when the carrier allows that.
CapabilitySupport.supported readonly number[] Exact versions this deployment implements, ascending. Never a range.
CARRIER_MECHANISMS enumeration —
CarrierMechanism type —
DiscoveryEntry.defaultVersion number —
DiscoveryEntry.supported readonly number[] —
negotiate function Choose a version, or refuse with a code that says which way the mismatch went.
NEGOTIATION_REASONS enumeration —
NEGOTIATION_VIOLATION_KINDS enumeration —
NegotiationOutcome type —
NegotiationReason type —
NegotiationViolationKind type —
validateCarriers function —
VERSION_CARRIERS constant The carriers, one per transport.
VersionBinding.version number —
VersionCarrier.negotiable boolean Whether the receiving side may answer with a different version.
VersionDeprecation.version number —

Deprecation#

Symbol Type Notes
DiscoveryEntry.deprecations readonly VersionDeprecation[] —
DiscoveryEntry.lifecycle Lifecycle —
VersionDeprecation.deprecatedIn number —
VersionDeprecation.sunsetOn Instant The date after which the version stops being served. Never null.

Evidence#

  • evidence/v1-workbenches/workbench-kit-export-map.json
  • evidence/v1-workbenches/workbench-kit-negotiation-fixtures.json
  • libs/oshun/workbench-kit/src/negotiation.ts