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.
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#
(typeof CARRIER_MECHANISMS)[number];
discoveryDocument#
Build the discovery document, for an AUTHENTICATED caller only.
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.
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#
| { 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#
(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#
(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#
(typeof REFUSAL_CODES)[number];
SYNCHRONOUS_TRANSPORTS#
The transports with a live counterparty at the moment the version is chosen.
Values: http, bridge
Transport#
(typeof TRANSPORTS)[number];
TRANSPORTS#
Values: http, event, job, bundle, bridge, generated-client
validateBinding#
S1.11.f — the negotiated version must reach every downstream key.
validateBinding(binding: VersionBinding, negotiatedVersion: number): readonly NegotiationViolation[]
validateCarriers#
validateCarriers(carriers: readonly VersionCarrier[]): readonly NegotiationViolation[]
validateDiscovery#
validateDiscovery(entries: readonly DiscoveryEntry[], now: Instant): readonly NegotiationViolation[]
validateSupport#
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
{
"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
{
"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
{
"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
{
"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.jsonevidence/v1-workbenches/workbench-kit-negotiation-fixtures.jsonlibs/oshun/workbench-kit/src/negotiation.ts