trace_context.bend checks

The field that a ZeroId error names: the trace ID or parent ID of a traceparent value, or a supplied span ID.

Why the strict codec, TraceId.parse, SpanId.parse or TraceParent.read refused a text. Offsets count Bend characters (Unicode code points) from zero at the start of the text, and the first problem in reading order is reported. UnexpectedEnd{offset} the text ends where a character is required InvalidHex{offset} this character is not a lowercase hex digit ExpectedSeparator{offset} this character should be "-" TrailingInput{} characters follow a complete value ForbiddenVersion{} the version is ff, forbidden by W3C 3.2.2.1 UnsupportedVersion{version} a version other than 00, which the strict codec does not read (TraceParent.read reads versions 01 to fe by their known prefix) ZeroId{field} the named ID is all zero, forbidden by W3C 3.2.2.3 and 3.2.2.4 ControlCharacter{offset} this character is a control character other than a horizontal tab, which no field value may hold (RFC 9110, section 5.5); only TraceParent.read reports it, in the fields of a later version that it does not read

Why creating a context from supplied IDs was refused: a child reused its parent's span ID, or a restart reused the received trace ID.

A sequence of n digits read from the front of a text, with the text that remains after it. The length n is part of the type, so a reader of 32 digits can only produce 32.

A strict traceparent v00 value (W3C 3.2.2): a trace ID of 32 digits and a parent ID of 16 digits, each with a proof that it is not all zero, and a flag byte of two digits. Length and alphabet are structural: a value with a wrong length or a non-hexadecimal digit cannot be built. All eight flag bits are kept, including the reserved ones, so the codec is exact.

A validated trace ID: 32 lowercase hexadecimal digits, not all zero (W3C 3.2.2.3). random records whether the random-trace-id flag (W3C 3.2.2.5.2) may be emitted for it. A parsed ID makes no such assertion: only its origin can justify one. Generation sets it, and a caller who knows the ID is random sets it with TraceId.assert_random.

A validated span ID: 16 lowercase hexadecimal digits, not all zero, the identifier of one operation. It is sent as the parent ID of traceparent (W3C 3.2.2.4).

How a child operation obtains its sampled indication (W3C 3.2.2.5.1): InheritSampled{} keeps the parent's and SetSampled{sampled} sets it. The indication communicates a decision; it does not record anything.

A context received from another participant. It identifies the sender's operation and keeps only the known flags: sampled and random-trace-id. It is built from a received value (RemoteContext.from_traceparent) and has its own type, so it cannot be sent as if it were this participant's operation.

A context that identifies an operation of this participant: the one it sends in its own headers. The Context.* operations build it.

The context whose trace a child operation continues: a received context or one of this participant's own operations.

Why generating identifiers failed. A source failure carries the source's own code and message; exhaustion names the identifier whose eight candidates were all rejected.

The words read so far for the current trace ID candidate, in arrival order. Four words complete a candidate.

The words read so far for the current span ID candidate. Two words complete a candidate.

The generation machine below is shared by the IO operations and stated in the laws. Its types and Draw functions are internal: callers use the Context.*_with operations or generation.bend, and a host that feeds words itself uses Generation.

What a new local context needs besides its span ID: the trace ID it belongs to, its sampled indication, and for a child the parent's span ID, which the new span ID must not repeat.

A generation in progress: drawing the trace ID or the span ID. remaining counts the further candidates allowed after the current one, so each identifier gets eight candidates in all. previous is the received trace ID that a restart must not reuse.

The state of a generation after each source word: it needs another word, it created a context, or it failed.

A generation with its word budget, for a host that feeds it one word at a time instead of passing a source as a template, such as JavaScript code calling this module: the words it may still read (fuel) and the machine's step. Its fields are internal, like Step: Generation.root and its siblings build one. Context.root_with and its siblings drive the same values, and a host that feeds words while Generation.needs says so gets the pure driver's result (law generation_drive).

Why a limit configuration was refused. The first failing rule is reported: TraceParentInputTooSmall{} the traceparent input budget is below 55 TraceStateOutputTooSmall{} the tracestate output budget is below 512 TraceStateInputTooSmall{} the tracestate input budget is below the output budget

Budgets in UTF-8 octets. The input budgets bound a received traceparent value and a combined tracestate value; the output budget is the most an emitted tracestate may take. evidence is the proof of Limits.is_valid, so every Limits value follows the rules.

Why a tracestate key, value or received member was refused: MissingEquals{} a nonempty member has no "=" InvalidKey{} the text before the first "=" is not a key InvalidValue{} the text after it, without trailing optional whitespace, is not a value

A tracestate key, naming the vendor that owns an entry. evidence proves the Level 2 key grammar for text, so a StateKey is always valid: build one with StateKey.parse (the negative fixture tests/reject/invalid_state_key.bend shows that direct construction with a wrong text does not compile).

A tracestate value, opaque to every other vendor. evidence proves the Level 2 value grammar for text. Leading spaces are part of the value.

Why a received tracestate value was discarded: StateTooLarge{} the combined value exceeds its input budget TooManyMembers{} a 33rd nonempty member was reached InvalidEntry{member, error} a member is invalid; member numbers the comma-separated members of the combined value from zero, empty members included Discarding the state never invalidates a valid traceparent (spec #1).

One vendor's entry: a key and its value.

Ordered vendor state: at most 32 entries with distinct keys, leftmost first. evidence proves both properties, so every TraceState has them (law state_valid).

Where reading the current member stands: before its key, with only optional whitespace so far; inside its key; or inside its value. Characters read are kept most recent first, so each one costs a single step.

A tracestate being read: the members ended so far, empty ones included; how many more nonempty members are allowed; the current member; and the first entry of each key, in reading order. Stopped holds the first problem found. The scan and its helpers are internal.

What truncation to the output budget kept, and the keys of the entries it dropped, in their original order. Reporting the keys, not the values, tells which vendors lost their state without repeating opaque data.

A local context and the state sent with it.

The two header values an outgoing context emits, and the keys of the entries that truncation to the output budget dropped, in their original order. A context with no state emits the tracestate "", which Context.inject does not write.

One field of a message: its name and its value. A carrier is the list of a message's fields in their order; repeated fields stay separate, as the message carried them. A host that joins repeated fields into one value with commas (RFC 9110, section 5.3) gives one field with that value.

Why extraction refused a message's traceparent: RepeatedTraceParent{} the message has more than one traceparent field, or a value that joins several with a comma TraceParentTooLarge{} the value exceeds the traceparent input budget InvalidTraceParent{error} the value breaks the rules of its version; error is the first problem, as the codec reports it, with offsets counted from the first character after optional whitespace The received value itself is never included.

The original fields of an accepted message: its traceparent value, without the optional whitespace around it, and its tracestate field values as they came, in arrival order, none when it had no tracestate field. They are what Context.forward sends. The input budgets bound the pairs that extraction keeps (law received_bounds); a pair built directly with this constructor carries no such guarantee, so forwarding checks what it sends. A pair that extraction kept is refused only when it exceeds the output budget (law forward_extracted).

A context extracted from a message: the sender's operation, the state that came with it, and the received pair when the whole pair was accepted. It is not this participant's operation: a service continues it with a child (Context.child_from_id with IncomingContext.parent), or forwards the received pair unchanged (Context.forward).

The context to continue from that extraction keeps when a message carries no usable traceparent: a context received earlier, or an operation of this participant with the state it sends.

What extraction found in the traceparent fields of a message: an accepted value, no field, or a refusal with its reason.

What extraction did with the tracestate fields of a message: StateAbsent{} there was no tracestate field StateAccepted{} the fields were read into the incoming state, which may be empty StateDiscarded{error} the fields were refused as a whole; the incoming context has no state and the traceparent stays accepted StateIgnored{} the fields were not read, because the message has no accepted traceparent (W3C 3.3)

The result of extracting a message: the context to continue from, if any, and what happened to each field. context is the incoming context of the message when its traceparent was accepted, and the base otherwise.

The carrier an injection writes, and the keys of the entries that truncation to the output budget dropped from the state, in their original order: diagnostics, kept apart from the carrier.

Why a received context could not be forwarded unchanged: NothingToForward{} it keeps no received pair: its tracestate was discarded when it was extracted ForwardTooLarge{} its tracestate fields, joined by commas, exceed the tracestate output budget InvalidForwardParent{error} its traceparent value is not one that TraceParent.read accepts InvalidForwardState{error} its tracestate fields are not ones that TraceState.parse_fields accepts A pair that extraction keeps always passes the last two checks (law forward_extracted); they refuse a pair built directly.

How a service takes the context that extraction keeps, the message's or the base: Continue{} continue it with a child Restart{} replace it with a new trace, as at a trust boundary: its trace ID is not reused, its state is discarded and the root defaults apply

What the operations do when generating an identifier fails: Lenient{} carry on without a new operation; the result says why Strict{} fail with the GenerationError, so that the caller can refuse the operation

How a service's operation came about: Continued{} a child of the context that extraction kept Started{} a root: extraction kept no context Restarted{} a new trace in place of the kept context (Restart{})

The service's own operation for a received message, with the state it sends, or the error that left it without one. received is the message's incoming context when the service continues it, kept so that a message it sends can forward the received pair if generating fails; it is None{} for a root, a restart or a continued base.

The service's operation as Context.continue_or_start_with decides it for a received message, before it reads any word: the generation to drive and what the generation's result makes of the service. ContinuePlan{generation, state, received} a child of the kept context, sending its state StartPlan{generation, origin, sampling} a root or a restart A host that feeds a generation one word at a time, such as JavaScript code calling this module, drives ServicePlan.generation and hands the result to ServicePlan.service (law hosted_service).

Why a message without a new operation does not forward a received pair: NothingKept{} the service keeps no received context: its operation is, or was to be, a root, a restart or a child of a base ForwardFailed{error} Context.forward refused the received context with error

The context fields of one message and how they came about: Fresh{operation, injection} a new operation, injected with the service's state Forwarded{carrier, error} no operation could be generated (error); the received pair is forwarded unchanged NoContext{carrier, error, no operation could be generated, and no reason} pair was forwarded (reason): the context fields are cleared

A message's operation as Context.send_with decides it before it reads any word, with the limits and the carrier to send it with: SendChild{generation, limits, outgoing, received, carrier} a child of the service's operation, injected with the service's state SendFallback{error, limits, received, carrier} no operation, for a service without one: the fallback, reading no word A host that feeds a generation one word at a time drives SendPlan.generation and hands the result to SendPlan.sent (law hosted_send).

Put one more digit in front of a parsed sequence: n digits become 1 + n.

A decoded character, or InvalidHex at its offset when it is not a lowercase hexadecimal digit.

Decode one character as a lowercase hexadecimal digit.

Consume exactly n characters as digits, keeping the unconsumed rest of the text. The recursion decreases n, so no length check or unchecked conversion is needed: the result's type already has length n.

The rest of the text after a "-", or ExpectedSeparator at its offset.

Read the "-" expected at offset.

The value must end here. Only the first character after it is inspected, so an arbitrarily long suffix is refused without being read.

The version digits: 00 is the only version the strict codec reads, ff is forbidden (W3C 3.2.2.1), and any other version is reported with its text.

Attach the proof that digits are not all zero, or fail with ZeroId naming the field.

Check that digits are not all zero (W3C 3.2.2.3, 3.2.2.4).

The last field: the two flag digits, then the end of the text.

After the trace ID: the parent ID, which must not be all zero, its "-" at offset 52 and the flag digits at offset 53.

After the version: the trace ID, which must not be all zero, its "-" at offset 35 and the parent ID from offset 36.

After the two version digits: the version check, the "-" at offset 2 and the trace ID from offset 3.

Parse a strict traceparent v00 value: exactly "00-", 32 lowercase hexadecimal digits, "-", 16 digits, "-" and two digits; the IDs must not be all zero. No whitespace, case folding or suffix is accepted, and every flag byte is kept as received. This is the strict wire codec, not a complete W3C propagator: TraceParent.read and Context.extract apply the processing rules of W3C 3.2.4 and 4.1.2, such as reading later versions by their known prefix. Laws: roundtrip, inverse and formatted_length.

The text of a strict v00 value: always 55 characters. It is total, because validity is carried by the argument's type, and it preserves every flag bit: it is the exact inverse of parse, not an outgoing-header policy (see LocalContext.to_traceparent for what a participant emits).

Whether the sampled flag, bit 0 of the flag byte, is set (W3C 3.2.2.5.1).

Whether the random-trace-id flag, bit 1, is set (W3C 3.2.2.5.2). It records the sender's assertion; it does not prove how the trace ID was generated.

The digits of a supplied ID must be the whole text, and not all zero.

A supplied ID is exactly n lowercase hexadecimal digits, not all zero.

Parse a supplied trace ID: exactly 32 lowercase hexadecimal digits, not all zero. Error offsets count from the start of the ID. The result makes no randomness assertion (laws trace_id_parse and trace_id_accepts).

Record the caller's assertion that these digits were generated randomly, so that the random-trace-id flag is emitted with them. The caller is responsible for the assertion; validation cannot establish it (law assert_random).

Whether the trace ID asserts that it was generated randomly.

The 32 lowercase hexadecimal digits of the trace ID.

Whether two trace IDs name the same trace. The randomness assertion is not part of the identifier, so it is ignored.

Parse a supplied span ID: exactly 16 lowercase hexadecimal digits, not all zero (laws span_id_parse and span_id_roundtrip).

The 16 lowercase hexadecimal digits of the span ID.

Whether two span IDs name the same operation.

The sampled indication a child receives: the inherited one, unless the caller set another (law sampling).

Interpret a received strict-v00 value as the sender's context. Bit 0 is sampled and bit 1 is random-trace-id; the reserved bits are not interpreted and do not travel with the context (law received_flags).

The trace the received context belongs to.

The sender's operation: the parent ID of the received value.

The sender's sampled indication.

The trace this participant's operation belongs to.

This participant's operation.

The sampled indication this participant sends.

The participating representation of a local context: version 00, and flags limited to sampled (bit 0) and random-trace-id (bit 1), with every reserved bit zero (W3C 3.2.2.5.3; laws emitted_traceparent and emitted_projection).

The trace a child continues.

The parent's operation, which a child must not reuse.

The sampled indication a child inherits by default.

Represent an operation the caller owns, with supplied IDs and an explicit sampled indication. The IDs must belong to that operation: validating their format cannot establish where they came from (law from_ids).

Start a trace with supplied IDs. A new root is not sampled (spec #1: "New roots default to sampled 0"; law root). generation.bend provides Context.root, Context.child and Context.restart for generated IDs.

The child, unless the span ID was found equal to the parent's.

Continue the parent's trace with a new operation identified by a supplied span ID. The child keeps the trace ID and its randomness assertion, and its span ID must differ from the parent's (ReusedSpanId otherwise). Sampling is inherited unless set. Laws: child, child_reuse and child_accepts.

The restarted root, unless the trace ID was found equal to the received one.

Start a new trace with supplied IDs instead of continuing a received context. The new trace ID must differ from the received one (ReusedTraceId otherwise), and the root defaults apply, sampled 0 included. Laws: restart, restart_reuse and restart_accepts.

The eight lowercase hexadecimal digits of a word, most significant first (laws hex_injective and word_hex).

A trace ID from nonzero digits, with no randomness assertion.

A trace ID from four words, read most significant first: the first word gives the first eight digits. Like a parsed ID it makes no randomness assertion; add one with TraceId.assert_random when the words are random. An all-zero candidate is None (laws trace_words and words_unasserted).

A span ID from nonzero digits.

A span ID from two words, most significant first. An all-zero candidate is None (law span_words).

A root draws its trace ID, then its span ID, and starts unsampled. Seven further candidates follow the first, eight in all.

A restart draws like a root but must not reuse the received trace ID.

A child keeps the parent's trace ID and draws a span ID other than the parent's.

Try another trace ID candidate, or fail once the eight are used.

An accepted trace ID is followed by the span ID, with the root default sampled indication.

A trace ID candidate equal to the received one is retried.

Check a complete trace ID candidate: zero and, for a restart, the received trace ID are retried; anything else is accepted.

Try another span ID candidate, or fail once the eight are used.

An accepted span ID completes the new local context.

A span ID candidate equal to the parent's is retried.

Check a complete span ID candidate: zero and, for a child, the parent's span ID are retried; anything else is accepted.

Generation reads its words from a source trusted to be random, so each trace ID candidate asserts random-trace-id.

Feed the next source word to the machine. A source error ends the generation at once with SourceFailure (law feed_failure); a word completes or extends the current candidate.

The result of a finished generation. A generation that has not finished would report the identifier it was drawing; the root_ends, child_ends and restart_ends laws show that the word budgets of the operations below make those cases unreachable.

Whether a generation has ended, with or without a context.

A deterministic word source for tests and replay: each read takes the next result, and an empty tape fails with code 1, tape-exhausted.

Feed a word that a source returned, keeping the source's next state.

Whether the generation in a driver's result has ended.

Drive a generation from a tape, reading one word at a time and stopping as soon as it ends; unread words stay on the tape. fuel bounds the steps, which Bend requires for termination; the laws show the budgets suffice.

The source's final state with the generation's result.

A root: at most 48 words, eight trace ID candidates of four words and eight span ID candidates of two.

A restart replacing previous: at most 48 words, as a root.

A child of parent: at most 16 words, eight span ID candidates.

Whether a step needs another word within fuel more words.

Whether the generation needs another word: it has not ended, and its budget allows one more.

The generation after word: the step it gives with one word less of budget, or, for a step that needs no word, the same step with none left.

Feed the generation the next word of its source (see Draw.feed). A generation that needs no word ignores it.

The generation's result: the context it created, or why it failed. One that still needs a word once its budget is spent has exhausted its candidates; the root_ends, child_ends and restart_ends laws show that the budgets suffice.

A deterministic source that replays a tape of word results.

The name of a codec or ID error, with its offset or, for an unsupported version, its two digits. ZeroId names the field: ZeroTraceId, ZeroParentId or ZeroSpanId.

The name of a context creation error.

The name of a generation error; a source failure adds the source's code and message.

The rules of a configuration, which must accept its own emitted representation: a traceparent input budget of at least 55 octets, the length of a v00 value, and a tracestate input budget no smaller than an output budget of at least 512 octets (spec #1, "Tracestate policy and resource bounds"; the 512-octet minimum comes from #8; law limits_bounds).

The first rule a refused configuration breaks.

The configuration, when the check found it valid.

Validate a configuration; budgets count UTF-8 octets (laws limits_new and limits_fields).

32 KiB for each received value and 512 octets for an emitted tracestate (law default_limits). The 512-octet output budget is this package's capacity policy, not a W3C maximum.

The most octets a received traceparent value may take.

The most octets a combined tracestate value may take, including the commas that join repeated fields.

The most octets an emitted tracestate may take.

The name of a limits error.

Whether a code point lies between two others, both included.

lcalpha / DIGIT: a lowercase ASCII letter (%x61-7A) or a digit (%x30-39), the first character of a key.

keychar: lcalpha / DIGIT / "_" / "-" / "*" / "/" / "@".

nblk-chr: %x21-2B / %x2D-3C / %x3E-7E, printable ASCII other than space, "," and "=". A value ends with one of these.

chr: %x20 / nblk-chr, a character of a value: nblk-chr or a space.

OWS: a space or a horizontal tab (RFC 9110, section 5.6.3).

Every remaining character is a key character, and at most room remain. The recursion stops once the room is used up, so a huge invalid key is not read to its end.

key = ( lcalpha / DIGIT ) 0*255( keychar ): 1 to 256 characters (W3C 3.3.2.2.1). Level 1's tenant@system restriction does not apply.

char is a value character followed by tail, of which at most room characters are allowed; the last character is not a space.

value = 0*255( chr ) nblk-chr: 1 to 256 printable ASCII characters other than "," and "=", the last of which is not a space (W3C 3.3.2.2.2).

The key, when the check found the text valid.

Accept exactly a Level 2 key, or fail with InvalidKey. Nothing is trimmed or folded (laws key_parse, key_roundtrip and key_separators).

The key's text.

The value, when the check found the text valid.

Accept exactly a Level 2 value, leading spaces included, or fail with InvalidValue. No whitespace is trimmed here, so a trailing space is refused (laws value_parse, value_roundtrip and value_separators).

The value's text.

The name of an entry error.

The entry's key.

The entry's value.

The text of the entry's key.

key=value, as the entry is sent.

Whether one of the entries has this key.

No entry repeats the key of an entry before it; seen holds the entries already passed. This is the order in which the reading machine checks keys.

Distinct keys and at most 32 entries (W3C 3.3.2 and 3.3.3).

The state with no entries. It formats as "".

The entries in order, leftmost first.

Whether the state has no entries.

The value of entry when its key matched, or the result for the rest.

The value of the first entry with this key.

The value of the entry with this key, if there is one (laws get_entry and get_absent). The key is validated, so a lookup never needs to check it.

Each entry after the first, preceded by its comma.

The entries as key=value, joined by commas.

The normalized value: the entries in order, joined by commas, with no optional whitespace. The empty state formats as "" (laws state_roundtrip and first_wins).

The UTF-8 octets of a character. Bend characters are Unicode code points, so this is the size of the character's UTF-8 encoding: 1 to 4.

The UTF-8 octets of a text, in which the laws state every budget. Emission measures keys and values with it, at most 256 characters each; parsing measures received text with Utf8.left instead, which stops counting past the budget.

What is left of a budget after taking need octets, or None when less remains.

What is left of a budget after a text, or None once the text exceeds it. Measuring stops at the first character beyond the budget, and a None budget stays None.

Fields after the first are measured with the comma that joins them. Once the budget is exceeded, no further field is visited.

What is left of a budget after repeated fields and the commas that join them.

A value's characters arrive most recent first. Restoring them skips optional whitespace until the first other character, then keeps every character, so the value comes back in reading order without its trailing whitespace.

The restoring loop: one character at a time, with the state (whether a character was kept yet, the value so far).

The value in reading order without its trailing optional whitespace.

A character of a member that has no key yet: optional whitespace is skipped, an "=" gives the member an empty key, which validation refuses, and anything else starts the key.

A character inside a key: the first "=" ends the key, anything else extends it. Key characters are validated when the member ends.

A character other than a comma extends the current member. Inside a value every character is kept; validation refuses those the grammar excludes.

Validate the key and value texts of a member that ended. An invalid key is reported before an invalid value.

Keep the entries unchanged when the key was present; otherwise add the entry at the end.

Keep only the first entry of each key (spec #1, "Preserve the first occurrence of a duplicate key").

A valid member counts toward the 32 allowed before duplicates are dropped (spec #1); with no room left, the state is discarded with TooManyMembers.

A member that ended: an invalid one stops reading with its number and reason; a valid one is counted and kept.

The current member ends at a comma or with the value. An empty member, or one of optional whitespace only, is ignored but still numbered; a member without "=" is refused; otherwise its key and value are validated, trailing optional whitespace left out of the value.

One character of a scan that is still reading: a comma ends the member, and anything else extends it.

Read one character, unless the scan has stopped.

Read a text one character at a time, stopping at the first problem. This is a loop (a tail call), so its depth does not grow with the text.

Fields after the first are read after the comma that joins them.

Read repeated fields as their comma-joined combination.

The scan of a new value: no member ended, 32 allowed, nothing kept.

The scan keeps only the first entry of each key and stops at a 33rd member, so this check is not expected to fail: the laws prove it passes for normalized values, and the corpus exercises the rest. A failure would be reported as too many members.

The state read, once the last member has ended. TraceState.is_valid is checked here to build the state's evidence.

The last member ends with the value.

Read the fields only when they fit the budget.

Parse repeated tracestate field values, in arrival order, as their comma-joined combination (W3C 3.3.2). The combined value, joining commas included, must fit the tracestate input budget; a larger one is refused with StateTooLarge before any member is read, without measuring the rest. Then: empty members are ignored, and so is optional whitespace before a member and after its value; every nonempty member must be a valid entry (InvalidEntry) and counts toward the 32 allowed (TooManyMembers); the first entry of each key is kept. An error discards the whole state; a valid traceparent stays valid (spec #1). W3C 3.3: parse tracestate only for a message whose traceparent was parsed. Laws: fields_join, over_budget, within_budgets, first_wins and the others of section 10 of LAWS.bend.

Parse one combined tracestate value; see TraceState.parse_fields.

The name of a tracestate error; InvalidEntry adds the member number and the reason.

item followed by rest, unless skip is True: one step of a filter. Removing a key and listing the dropped keys both use it.

The entries without the one whose key is key, in order.

The state of these entries when the check finds them valid, fallback otherwise. Updates build their entries so that the check passes, which the laws prove; fallback keeps the function total without an unchecked conversion.

The state of entries, checked, or fallback if the check fails.

Add or update the entry of key (W3C 3.5): it goes to the front with value, and the other entries follow in their order. At most 31 of them stay, so a new key in a full state removes the last entry, while updating a key that is present evicts nothing (laws set_entries, update_keeps_all, insert_entries and set_get).

Delete the entry of key, if there is one; the other entries keep their order (W3C 3.5; laws remove_entries and remove_get). W3C asks participants not to delete keys other vendors generated: that breaks correlation in their systems.

The octets of key=value (law entry_size).

The octets of each entry after the first, with its comma.

The octets of the entries joined by commas, as Entries.format writes them.

The octets of TraceState.format(state) (law state_size).

The state that fits the output budget.

The keys of the entries removed, in their original order; none when the state already fitted.

Whether the entry is larger than 128 octets. W3C 3.3.3.1 asks to remove such entries first.

Whether one of the entries is larger than 128 octets.

The entries without the rightmost one larger than 128 octets: an entry stays when a large entry follows it.

The entries without the rightmost one.

One removal step (spec #1): the rightmost entry larger than 128 octets, or the rightmost entry when none is.

Remove entries one step at a time while they take more than budget octets, and stop as soon as they fit. fuel bounds the steps. One per entry suffices: once every entry is removed, the empty list takes 0 octets, which fits any budget.

The keys of the entries that kept lacks, in order.

Fit a state to the output budget of limits by removing whole entries (W3C 3.3.3.1, spec #1): while the value is over the budget, remove the rightmost entry larger than 128 octets, or the rightmost entry when none is, and stop as soon as it fits. The surviving entries keep their order (laws truncate_steps, truncate_fits, truncate_whole, truncate_order and truncate_dropped).

An outgoing context with no state yet, as for a new root.

An outgoing context that sends state, such as the state received with the parent of a child operation. The caller associates the state with this operation, as with Context.from_ids.

The local operation.

The state sent with the operation.

The value of the entry with this key, if there is one.

Add or update an entry (see TraceState.set); the context is unchanged (law outgoing_set).

Delete an entry (see TraceState.remove); the context is unchanged (law outgoing_remove).

The emission of a context and a truncated state.

The traceparent and tracestate values to send: the participating traceparent of the context, and the normalized value of the state truncated to the output budget of limits (laws emit_traceparent, emit_tracestate, emit_fits and emit_accepted).

The traceparent value: always 55 characters.

The tracestate value: at most the output budget in octets, "" for no state.

The keys of the entries truncation dropped, in their original order.

The field's name.

The field's value.

Whether text is name without regard to ASCII case (W3C 3.2.1 and 3.3.1): each character of text, with the letters A to Z lowered, is the character of name at its position. Other characters are compared as they are, so a name that differs by more than ASCII case names another field. name is written in lowercase, and the comparison follows it, so a long field name is not read past it.

value before found when hit is True: one step of Carrier.values.

The values of the fields named name, most recent first, before found.

The values of the fields named name without regard to ASCII case, in their order: the loop collects them most recent first, and reversing, also a loop, puts them back in order.

head followed by tail, without the optional whitespace at its start: ows says whether head is optional whitespace.

The text without the optional whitespace, spaces and horizontal tabs, at its start.

The text without the optional whitespace at its start and at its end (RFC 9110, section 5.5: "A field value does not include leading or trailing whitespace"). Reversing brings the end to the front, and reversing again brings it back.

Whether the text contains a comma: found records whether one was seen before.

Whether the text contains a comma.

Whether a character is a control character other than a horizontal tab: U+0000 to U+0008, U+000A to U+001F or U+007F. No field value may hold one (RFC 9110, section 5.5); a carriage return or a line feed would end the field.

The offset of the first control character of text, counted from offset, unless found already holds one. This is a loop.

Whether a value's version, from its two digits, is later than 00 and so read by its known prefix (W3C 3.2.2.1 and 3.2.4): Done{False{}} for 00, which the strict codec reads, Done{True{}} for 01 to fe, and a refusal for ff.

Whether the version whose two digits were read is later than 00.

The fields a later version does not know, once searched for a control character: none, or the offset of the first.

What may follow the flags of a later version: the end of the value, or a dash that starts fields this version does not know. Those fields are not read (W3C 3.2.4: "Vendors MUST NOT parse or assume anything about unknown fields"), except that a control character in them is refused with ControlCharacter at its offset: no field value may hold one (RFC 9110, section 5.5), and a value forwarded unchanged must not end a message's field. Any other character than a dash at offset 55 is ExpectedSeparator.

A later version is read by its known prefix (W3C 3.2.4 and 4.1.2): its first 55 characters are read as version 00, which checks the trace ID, the parent ID, the flags and the dashes between them at their own offsets, and then the value must end or continue with a dash. A value that ends before its 55th character, with no invalid character before, fails with UnexpectedEnd.

Read a value by the rules of its version: later is False for 00.

The known fields of a value, read by the rules of its version.

A refusal of the codec, as a refused traceparent.

A value that joins several with a comma is refused as repeated fields; any other value is read by the rules of its version.

A value without the whitespace around it, refused when it joins several.

A value within its budget is read without the optional whitespace around it; a value over the budget is refused without being read further.

Read one received traceparent value by the rules of a participant, and return its known fields as a v00 value, flag byte included: - a value over the traceparent input budget of limits, counted in UTF-8 octets with its whitespace, is refused with TraceParentTooLarge; - optional whitespace around the value is removed (RFC 9110, section 5.5); - a value with a comma joins repeated fields and is refused with RepeatedTraceParent, even when the comma is in fields of a later version: no version defines a comma, and a host that joins repeated fields separates them with one (RFC 9110, section 5.3); - version 00 is read exactly by TraceParentV00.parse: 55 characters and nothing after them; - version ff is refused with ForbiddenVersion (W3C 3.2.2.1); - versions 01 to fe are read by their known prefix: the fields of version 00, followed by the end of the value or by a dash and fields that are not read, whatever they hold other than a comma or a control character, which is refused with ControlCharacter (W3C 3.2.4 and 4.1.2; RFC 9110, section 5.5). RemoteContext.from_traceparent then keeps the sampled and random-trace-id flags. Laws: read_v00, read_v00_exact, read_future, read_ff, read_comma, read_over_budget and read_within_budgets.

The state outcome when the tracestate fields are not read: absent without a field, ignored with one (W3C 3.3).

The extraction of a message whose context is not read: the base is kept, with the traceparent outcome and the presence of tracestate fields.

The incoming context of an accepted message, as the context to continue from.

An accepted message whose tracestate fields were parsed: an accepted state keeps the pair, which can be forwarded, and a refused one is discarded whole, keeping the traceparent (spec #1) but no pair, since the pair was not accepted whole.

An accepted message with its tracestate field values, read in arrival order as their comma-joined combination (W3C 3.3.2).

The extraction of a message whose only traceparent value value was read. The value is kept without the whitespace around it only once accepted, so a refused value is not read further.

The extraction of a message with these traceparent and tracestate field values.

Extract the trace context of a received message from its carrier, with base as the context to keep when the message has no usable traceparent (spec #1, user stories 14, 15, 16, 24 and 25): - no traceparent field keeps the base, TraceParentAbsent{}; - more than one traceparent field, whatever the case of their names, is refused, and so is a single value that TraceParent.read refuses; the base is kept, TraceParentRejected{error}; - an accepted value gives the incoming context and replaces the base: its tracestate fields, whatever the case of their names, are read in arrival order as their comma-joined combination, within the tracestate input budget; refused fields are discarded whole, keeping the traceparent; - without an accepted traceparent, tracestate fields are not read. Laws: extract_absent, extract_repeated, extract_refused, extract_read, state_independent and received_bounds.

The context to continue from: this message's incoming context when its traceparent was accepted, the base otherwise.

What extraction found in the traceparent fields.

What extraction did with the tracestate fields.

The incoming context an accepted message gives as its context.

This message's own context: the incoming context when its traceparent was accepted, None{} when extraction kept the base.

The context this message carried, when its traceparent was accepted; None{} when extraction kept the base, even an incoming one.

The sender's operation.

The state received with it: empty when the message had none or when it was discarded.

The received pair, when the whole pair was accepted: None{} when the tracestate was discarded.

The received context as the parent of a child operation.

The received traceparent value, without the whitespace around it.

The received tracestate field values, in arrival order.

The base as the parent of a child operation: a received context or an operation of this participant.

The state that goes with the base: the state received with an incoming context, or the state an outgoing context sends.

The name of a traceparent error; InvalidTraceParent adds the codec's error.

The name of a traceparent outcome; a rejection adds its error.

The name of a tracestate outcome; a discard adds its error.

Both outcomes of an extraction, for a log line: "TraceParentAccepted, StateDiscarded InvalidEntry 1 MissingEquals" for example. No received value is included, so the line can be logged as it is.

Whether a field name is traceparent or tracestate, without regard to ASCII case.

header before kept unless it is a context field (context_field): one step of Carrier.unrelated.go.

The unrelated fields, those that are not context fields, most recent first, before kept. This is a loop, so a message with many fields needs no deep stack.

The carrier's unrelated fields, followed by fields: reversing the loop's result onto fields, also a loop, puts them back in order.

The context fields of a traceparent value and a tracestate value, with lowercase names; the tracestate field is left out when its value is empty.

Remove every traceparent and tracestate field, whatever the case of its name, and keep the other fields in their order: the carrier of a message sent without context (spec #1, "Provide explicit context-field cleanup for the no-context path"). Law: clear_carrier.

The injection of an emission into a carrier.

Write an outgoing context into a carrier as a participant: the context fields of the carrier are replaced by the emitted traceparent, version 00 with only the sampled and random-trace-id flags, and the emitted tracestate, truncated to the output budget of limits and left out when empty. The other fields keep their order, and injecting the same context into the carrier written gives that carrier again. A receiver that extracts the carrier with the same limits continues the injected operation with the truncated state. Laws: inject_carrier, inject_dropped, inject_idempotent and inject_extracted.

The carrier to send.

The keys of the entries truncation dropped, in their original order; none when the state fitted.

The fields joined by commas, most recent character first, after done: each field is reversed onto the comma before it. This is a loop.

The fields joined by commas into one value, as String.join(fields, ",") writes it. It is built by loops, so fields of any length need no deep stack.

The carrier with its context fields replaced by a received pair: the traceparent value, and the tracestate fields joined into one value, left out when empty.

The last check of a forwarded pair: its tracestate fields parse.

The second check of a forwarded pair: its traceparent value reads back.

The first check of a forwarded pair: its tracestate fields, joined by commas, fit the output budget. Measuring stops past the budget.

Forward the received pair, if there is one.

Forward a received context unchanged into a carrier: its context fields are replaced by the traceparent value of the received pair and by its tracestate fields joined into one field, and the other fields keep their order. The pair must be there, its tracestate must fit the output budget of limits whole, and both fields must read back under limits; otherwise forwarding fails with a ForwardError and writes nothing, so a received traceparent never travels with an edited or truncated tracestate (W3C 3.4). The pair of a context that extraction accepted is refused only when its tracestate exceeds the output budget, and forwarding again into the carrier written gives that carrier again. Laws: forward_carrier, forward_nothing, forward_too_large, forward_extracted and forward_idempotent.

The name of a forwarding error; an invalid field adds its error.

The type an operation returns under policy: the value itself with Lenient{}, and the value or the GenerationError with Strict{}.

A value under policy: itself with Lenient{}, and what strict makes of it with Strict{}.

The source's final state with a value under policy.

A new trace's operation with the sampled indication that sampling resolves from the root default, not sampled: InheritSampled{} has nothing to inherit, and SetSampled{} sets its own.

The service that a child of the kept context gives, with state, or Untraced with the error.

The service that a new trace gives: the sampling of Serve.start and no state, or Untraced with the error. A new trace keeps no received pair.

The context that a restart replaces, as Generation.restart takes it: an incoming base's received context, or an outgoing base's operation as another participant receives it. The new trace ID reuses neither.

Continue the kept context with a child, with its parent and state, or replace it with a new trace, as reception says.

Take the context that extraction keeps, or start a root without one.

The plan of the service's operation for a message (see ServicePlan).

The generation that the plan drives.

The service that the result of the plan's generation gives, before the policy applies: its operation, or Untraced with the error.

The source's final state with the service that the plan gives.

A service without an operation as the GenerationError that caused it.

The fallback when a forwarding of the received pair was tried.

The fields a message carries when no operation could be generated: the received pair forwarded unchanged if it can be, and no context fields otherwise.

The message that a generated child gives: the child injected with the service's state, or the fallback.

The plan of one message that the service sends (see SendPlan).

The generation that the plan drives. A service without an operation has none to drive: its generation has already failed with the service's error, so that a host reads no word.

The message that the result of the plan's generation gives, before the policy applies. The fallback of a service without an operation does not depend on it.

The source's final state with the message that the plan gives.

A message without a new operation as the GenerationError that caused it.

The name of an origin.

How the service's operation came about; None{} without an operation.

The service's operation with the state it sends; None{} without one.

Why the service has no operation; None{} with one.

Add or update an entry of the state that the service's operation sends, such as this participant's own (see OutgoingContext.set). A service without an operation is unchanged: it sends no state of its own.

Delete an entry of the state that the service's operation sends (see OutgoingContext.remove). A service without an operation is unchanged.

The name of a service's origin, or Untraced with its error. It includes no received value.

Why no pair was forwarded: NothingKept, or the ForwardError's name.

The fields to send with the message, in every case.

The new operation that the message carries; None{} for a fallback.

Why no operation could be generated; None{} for a new operation.

The keys that truncating the service's state to the output budget dropped from a new operation's message (see Injection.dropped); none for a fallback, which sends no state of its own.

The name of a new operation's message, saying whether its state was truncated.

The name of a message's context: Fresh, saying whether its state was truncated, or for a fallback why no operation was generated and, without a forwarded pair, why none was forwarded. It includes no received value.

Drive a generation from any source. read returns the source's next state with each word, one word at a time, and the driver stops as soon as the generation ends; the final source state is handed back, so a caller can see what was read. fuel bounds the words read, as in Draw.run. Templates keep this driver free of any host effect: the effect, if any, lives in the source.

Turn the driver's final step into the generation's result.

Drive a generation from a caller's source, one word at a time (Draw.read), and hand back the source's final state with the result.

Generated contexts from a caller's source. read returns the source's next state with each word result. The source is trusted to be random: a generated trace ID asserts random-trace-id. A root or restart reads at most 48 words, and a child at most 16 (Generation.root and its siblings). Laws: root_tape, root_ends, root_exhaustion and generated_root.

A generated child of parent from a caller's source: at most 16 words. Laws: child_tape, child_ends, child_exhaustion and generated_child.

A generated restart replacing previous from a caller's source: at most 48 words. Laws: restart_tape, restart_ends and generated_restart.

Drive the plan's generation from a caller's source.

The service for a message, before the policy applies.

Give a service its own operation for a received message, from a caller's source (see the section's introduction). Laws: continue_usable, restart_usable, start_unusable and restart_keeps_nothing.

Drive the plan's generation from a caller's source.

Give one message that the service sends the context of a new operation, from a caller's source (see the section's introduction). carrier is the message's own fields; its old context fields are replaced in every case. Laws: send_operating, send_untraced and send_reports_generated.