log-foundry 0.2.1.dev3__tar.gz → 0.2.1.dev5__tar.gz

{log_foundry-0.2.1.dev3 → log_foundry-0.2.1.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.2.1.dev3
+Version: 0.2.1.dev5
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -206,6 +206,12 @@ never crashes the worker or the app. If the bounded queue fills completely, new
 dropped (newest-first) and counted rather than blocking your code. On `shutdown()` the worker
 stops, sweeps anything still queued into one final batch, emits it, and closes the sink.
 
+Both triggers can be pre-empted: `flush()` puts a marker in the queue and the worker emits the
+pending pile the moment it reaches it, ignoring the count and time triggers. Because the queue
+is FIFO, everything submitted before the call is necessarily ahead of that marker — which is
+exactly why the guarantee is "events submitted before this call", and why concurrent
+submissions from other threads may or may not be included.
+
 ## Usage
 
 ### `configure(...)`
@@ -292,6 +298,75 @@ def process_payment(user_id: int) -> str:
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
+### Continuing a trace across processes
+
+A trace stops at the process boundary: `@trace` mints a fresh `trace_id` whenever no span is
+open, so two processes cooperating on one logical operation produce two unrelated traces. Pass
+the context across and they join up. Nothing here is serverless-specific — the same two calls
+join an HTTP client to its server, or a Celery caller to its worker.
+
+**The producer publishes where it is:**
+
+```python
+@lf.trace
+def enqueue_check(location: str) -> None:
+    sqs.send_message(
+        QueueUrl=QUEUE_URL,
+        MessageBody=json.dumps({
+            "location": location,
+            "traceparent": lf.current_traceparent(),      # "00-<trace_id>-<span_id>-01"
+            "baggage": lf.current_baggage_header(),       # "request_id=req-123,tenant=acme"
+        }),
+    )
+```
+
+**The consumer adopts it — one line, and make it the first line:**
+
+```python
+@lf.trace
+def handler(event, context):
+    lf.continue_trace(event.get("traceparent"), baggage=event.get("baggage"))
+    lf.info("inspecting")          # same trace_id as the producer; parent is its span
+    try:
+        return inspect(event)
+    finally:
+        lf.flush()
+```
+
+| Call | Does |
+|---|---|
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
+| `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
+| `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+
+Details worth knowing:
+
+- **Call `continue_trace()` on the first line.** `@trace` opens the handler's span *before* the
+  body runs, so the call re-parents that span in place and rewrites the events it has already
+  buffered. A child span that already finished has been handed to the worker and can no longer
+  be moved.
+- **Only a root span is re-parented.** A nested span already belongs to an in-process trace, and
+  moving it would sever it from its own parent. The adopted context still applies to the next
+  root span opened in that context.
+- **Your `span_id` is never overwritten.** The adopting span keeps its own identity and takes the
+  inbound span as its `parent_span_id` — otherwise two processes would share a span id.
+- **`parent_span_id` may be omitted.** With only `trace_id` you join the trace as another root,
+  which beats being in a fresh trace when you know the trace but not the specific parent.
+- **Inbound context is untrusted and validated strictly** — 32/16 lowercase hex, all-zero ids
+  rejected, higher `traceparent` versions accepted per the W3C forward-compatibility rule.
+  Anything unusable is ignored with a single bounded warning on stderr and a fresh trace is
+  minted; a malformed id never reaches the event stream. Adopting a context grants **nothing**
+  — it selects a correlation id and confers no authority.
+- **Baggage fails independently of the trace.** A malformed `baggage` header is skipped with a
+  warning while the trace is still adopted: losing correlating fields is bad, losing the trace
+  join because one field was malformed is worse. Headers over 8192 bytes are rejected. Values
+  are percent-encoded, so `,` `=` and non-ASCII round-trip; non-string values are serialized
+  with `str()`, so a dict arrives as its repr.
+- **Sampling is not honoured.** `traceparent`'s flags byte is parsed and ignored, and outbound
+  is always `01`: this library records every span, so respecting another system's sampling
+  decision would mean dropping them.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
@@ -494,17 +569,70 @@ a failing sink with backoff, and applies backpressure so a slow or down sink can
 back-pressure the app: when its bounded queue is full it drops the newest submissions and counts
 them (`worker.dropped`) rather than stalling.
 
-Because delivery is asynchronous, drain before the process exits:
+Because delivery is asynchronous, drain before the process exits. There are two drains, and
+which one you want depends on whether the process is about to end:
 
 ```python
 import log_foundry as lf
 
-lf.shutdown()   # flush buffered events and close the sink; blocks until drained
+lf.flush()      # drain to the sink and keep going; returns True when everything landed
+lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
 ```
 
+| | `flush()` | `shutdown()` |
+|---|---|---|
+| Drains buffered events | yes | yes |
+| Closes the sink | no | yes |
+| Worker survives | yes | **no** — it never comes back |
+| Repeatable | yes | idempotent, but only the first call does anything |
+| Use it | before returning from a handler, or at a checkpoint | once, as the process exits |
+
 `shutdown()` is also registered via `atexit`, so a normal exit flushes automatically — call it
-explicitly when you need to be certain the tail reached the sink before a fast exit (e.g. at the
-end of a short script or an AWS Lambda handler). It is idempotent.
+explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
+end of a short script. It is idempotent.
+
+`flush(timeout=5.0)` returns `True` when every event submitted before the call has been passed
+to the sink, and `False` if that did not happen within `timeout` (or the worker was already shut
+down). It never raises — a logging call must not be the reason your function fails. Passing
+`timeout=None` waits indefinitely, which is unsafe anywhere with an execution deadline.
+
+#### Serverless / short-lived processes
+
+In AWS Lambda (and anything else that freezes rather than exits) the rules are different, and
+getting them wrong is silent:
+
+- **Flush before the handler returns.** Lambda freezes the execution environment the instant
+  your handler returns, so the worker's interval-based flush stops mid-interval and whatever is
+  still queued is lost when the container is eventually reaped. `atexit` does not save you —
+  a frozen environment is killed without running exit handlers, so `flush()` is the *only*
+  guaranteed drain there.
+- **Put it in a `finally`.** A flush written as the last line of the handler body is precisely
+  the line that does not run when the handler raises, and the invocation whose logs are most
+  worth having is the one that failed.
+- **Never call `shutdown()` per invocation.** It is terminal: the worker does not come back, so
+  the first invocation on a warm container would log and every later one would silently log
+  nothing. That failure reads as "works locally, broken in production".
+
+```python
+import log_foundry as lf
+from log_foundry.sinks.sqs import SQSSink
+
+lf.configure(service="billing-api", env="prod", sink=SQSSink(queue_url=QUEUE_URL))
+
+@lf.trace
+def handler(event, context):
+    lf.info("received", records=len(event["Records"]))
+    try:
+        return do_work(event)
+    finally:
+        lf.flush()      # in `finally`: the failed invocation is the one worth logging.
+                        # NEVER shutdown() here — the worker does not come back, and every
+                        # later invocation on this warm container would log nothing.
+```
+
+By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
+them into one — a step function, a producer and its consumer — pass the context across with
+[`continue_trace()`](#continuing-a-trace-across-processes).
 
 ## Event schema
 

{log_foundry-0.2.1.dev3 → log_foundry-0.2.1.dev5}/README.md

@@ -170,6 +170,12 @@ never crashes the worker or the app. If the bounded queue fills completely, new
 dropped (newest-first) and counted rather than blocking your code. On `shutdown()` the worker
 stops, sweeps anything still queued into one final batch, emits it, and closes the sink.
 
+Both triggers can be pre-empted: `flush()` puts a marker in the queue and the worker emits the
+pending pile the moment it reaches it, ignoring the count and time triggers. Because the queue
+is FIFO, everything submitted before the call is necessarily ahead of that marker — which is
+exactly why the guarantee is "events submitted before this call", and why concurrent
+submissions from other threads may or may not be included.
+
 ## Usage
 
 ### `configure(...)`
@@ -256,6 +262,75 @@ def process_payment(user_id: int) -> str:
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
+### Continuing a trace across processes
+
+A trace stops at the process boundary: `@trace` mints a fresh `trace_id` whenever no span is
+open, so two processes cooperating on one logical operation produce two unrelated traces. Pass
+the context across and they join up. Nothing here is serverless-specific — the same two calls
+join an HTTP client to its server, or a Celery caller to its worker.
+
+**The producer publishes where it is:**
+
+```python
+@lf.trace
+def enqueue_check(location: str) -> None:
+    sqs.send_message(
+        QueueUrl=QUEUE_URL,
+        MessageBody=json.dumps({
+            "location": location,
+            "traceparent": lf.current_traceparent(),      # "00-<trace_id>-<span_id>-01"
+            "baggage": lf.current_baggage_header(),       # "request_id=req-123,tenant=acme"
+        }),
+    )
+```
+
+**The consumer adopts it — one line, and make it the first line:**
+
+```python
+@lf.trace
+def handler(event, context):
+    lf.continue_trace(event.get("traceparent"), baggage=event.get("baggage"))
+    lf.info("inspecting")          # same trace_id as the producer; parent is its span
+    try:
+        return inspect(event)
+    finally:
+        lf.flush()
+```
+
+| Call | Does |
+|---|---|
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
+| `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
+| `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+
+Details worth knowing:
+
+- **Call `continue_trace()` on the first line.** `@trace` opens the handler's span *before* the
+  body runs, so the call re-parents that span in place and rewrites the events it has already
+  buffered. A child span that already finished has been handed to the worker and can no longer
+  be moved.
+- **Only a root span is re-parented.** A nested span already belongs to an in-process trace, and
+  moving it would sever it from its own parent. The adopted context still applies to the next
+  root span opened in that context.
+- **Your `span_id` is never overwritten.** The adopting span keeps its own identity and takes the
+  inbound span as its `parent_span_id` — otherwise two processes would share a span id.
+- **`parent_span_id` may be omitted.** With only `trace_id` you join the trace as another root,
+  which beats being in a fresh trace when you know the trace but not the specific parent.
+- **Inbound context is untrusted and validated strictly** — 32/16 lowercase hex, all-zero ids
+  rejected, higher `traceparent` versions accepted per the W3C forward-compatibility rule.
+  Anything unusable is ignored with a single bounded warning on stderr and a fresh trace is
+  minted; a malformed id never reaches the event stream. Adopting a context grants **nothing**
+  — it selects a correlation id and confers no authority.
+- **Baggage fails independently of the trace.** A malformed `baggage` header is skipped with a
+  warning while the trace is still adopted: losing correlating fields is bad, losing the trace
+  join because one field was malformed is worse. Headers over 8192 bytes are rejected. Values
+  are percent-encoded, so `,` `=` and non-ASCII round-trip; non-string values are serialized
+  with `str()`, so a dict arrives as its repr.
+- **Sampling is not honoured.** `traceparent`'s flags byte is parsed and ignored, and outbound
+  is always `01`: this library records every span, so respecting another system's sampling
+  decision would mean dropping them.
+
 ### Sinks
 
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
@@ -458,17 +533,70 @@ a failing sink with backoff, and applies backpressure so a slow or down sink can
 back-pressure the app: when its bounded queue is full it drops the newest submissions and counts
 them (`worker.dropped`) rather than stalling.
 
-Because delivery is asynchronous, drain before the process exits:
+Because delivery is asynchronous, drain before the process exits. There are two drains, and
+which one you want depends on whether the process is about to end:
 
 ```python
 import log_foundry as lf
 
-lf.shutdown()   # flush buffered events and close the sink; blocks until drained
+lf.flush()      # drain to the sink and keep going; returns True when everything landed
+lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
 ```
 
+| | `flush()` | `shutdown()` |
+|---|---|---|
+| Drains buffered events | yes | yes |
+| Closes the sink | no | yes |
+| Worker survives | yes | **no** — it never comes back |
+| Repeatable | yes | idempotent, but only the first call does anything |
+| Use it | before returning from a handler, or at a checkpoint | once, as the process exits |
+
 `shutdown()` is also registered via `atexit`, so a normal exit flushes automatically — call it
-explicitly when you need to be certain the tail reached the sink before a fast exit (e.g. at the
-end of a short script or an AWS Lambda handler). It is idempotent.
+explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
+end of a short script. It is idempotent.
+
+`flush(timeout=5.0)` returns `True` when every event submitted before the call has been passed
+to the sink, and `False` if that did not happen within `timeout` (or the worker was already shut
+down). It never raises — a logging call must not be the reason your function fails. Passing
+`timeout=None` waits indefinitely, which is unsafe anywhere with an execution deadline.
+
+#### Serverless / short-lived processes
+
+In AWS Lambda (and anything else that freezes rather than exits) the rules are different, and
+getting them wrong is silent:
+
+- **Flush before the handler returns.** Lambda freezes the execution environment the instant
+  your handler returns, so the worker's interval-based flush stops mid-interval and whatever is
+  still queued is lost when the container is eventually reaped. `atexit` does not save you —
+  a frozen environment is killed without running exit handlers, so `flush()` is the *only*
+  guaranteed drain there.
+- **Put it in a `finally`.** A flush written as the last line of the handler body is precisely
+  the line that does not run when the handler raises, and the invocation whose logs are most
+  worth having is the one that failed.
+- **Never call `shutdown()` per invocation.** It is terminal: the worker does not come back, so
+  the first invocation on a warm container would log and every later one would silently log
+  nothing. That failure reads as "works locally, broken in production".
+
+```python
+import log_foundry as lf
+from log_foundry.sinks.sqs import SQSSink
+
+lf.configure(service="billing-api", env="prod", sink=SQSSink(queue_url=QUEUE_URL))
+
+@lf.trace
+def handler(event, context):
+    lf.info("received", records=len(event["Records"]))
+    try:
+        return do_work(event)
+    finally:
+        lf.flush()      # in `finally`: the failed invocation is the one worth logging.
+                        # NEVER shutdown() here — the worker does not come back, and every
+                        # later invocation on this warm container would log nothing.
+```
+
+By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
+them into one — a step function, a producer and its consumer — pass the context across with
+[`continue_trace()`](#continuing-a-trace-across-processes).
 
 ## Event schema
 

{log_foundry-0.2.1.dev3 → log_foundry-0.2.1.dev5}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.2.1.dev3"
+version = "0.2.1.dev5"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.34"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

log_foundry-0.2.1.dev5/src/log_foundry/__init__.py

@@ -0,0 +1,84 @@
+"""log_foundry — consistent, structured logs per decorated function call.
+
+Public façade (module-function shape). Exposes configuration, the ``@trace`` decorator, the
+``debug/info/warning/error/critical`` emitters, ``set_baggage``, the cross-process propagation
+pair (``continue_trace`` to adopt an inbound context; ``current_traceparent`` /
+``current_trace_context`` / ``current_baggage_header`` to publish this one), ``flush`` (drain and
+keep logging) and ``shutdown`` (drain, close the sink, and stop).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from log_foundry.api import critical, debug, error, info, set_baggage, warning
+from log_foundry.config import configure, get_config
+from log_foundry.context import (
+    current_baggage_header,
+    current_trace_context,
+    current_traceparent,
+)
+from log_foundry.decorator import continue_trace, trace
+
+try:
+    # Distribution name ("log-foundry") differs from the import name ("log_foundry").
+    __version__ = _dist_version("log-foundry")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0"
+
+
+def flush(timeout: float | None = 5.0) -> bool:
+    """Drain buffered events through the sink without closing it.
+
+    Every event submitted before this call has been passed to ``sink.emit`` when it returns
+    ``True``. (Events submitted concurrently by another thread may or may not be included —
+    the caller cannot have meant those.) Unlike :func:`shutdown` the background worker stays
+    alive and the sink stays open, so logging continues normally afterwards.
+
+    This is the drain for a process that is *frozen* rather than exited — an AWS Lambda
+    handler must drain before it returns, but will be invoked again on the same warm
+    container. Call it in a ``finally``: the invocation worth logging is the one that failed.
+
+    ``timeout=None`` waits indefinitely, which is unsafe in any environment with an execution
+    deadline — it converts "some logs were lost" into "the invocation timed out".
+
+    Returns ``False`` if the drain did not complete within ``timeout``, or if the worker has
+    already been shut down. Never raises.
+    """
+    from log_foundry.decorator import _flush_worker
+
+    return _flush_worker(timeout)
+
+
+def shutdown() -> None:
+    """Flush buffered events and close the sink, blocking until drained. Idempotent.
+
+    Also registered via ``atexit``; call it explicitly before a fast process exit when you
+    want to be certain the tail of the queue reached the sink (SPEC-004 FR-005).
+
+    This is **terminal** — the worker does not come back. Do not call it per-invocation in a
+    serverless handler: the first invocation on a warm container would log and every later one
+    would silently log nothing. Use :func:`flush` there, which drains and keeps the worker.
+    """
+    from log_foundry.decorator import _shutdown_worker
+
+    _shutdown_worker()
+
+
+__all__ = [
+    "configure",
+    "get_config",
+    "trace",
+    "debug",
+    "info",
+    "warning",
+    "error",
+    "critical",
+    "set_baggage",
+    "continue_trace",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
+    "flush",
+    "shutdown",
+    "__version__",
+]

log_foundry-0.2.1.dev5/src/log_foundry/context.py

@@ -0,0 +1,160 @@
+"""Context propagation: span stack + baggage via contextvars (arch §5, guide Phase 4).
+
+``contextvars`` (not thread-locals) is correct under both threads and asyncio — each task
+inherits its own copy — so ``log_foundry.info(...)`` can find "the span I'm inside" with no
+manual passing. This module holds a *stack* of active spans (the top is the current span and
+the parent of the next nested call) plus trace-scoped baggage.
+
+Two footguns, both avoided below:
+  * Never mutate a ContextVar's default mutable value — the ``()`` / ``{}`` defaults are shared
+    across all contexts. Always ``.set()`` a new tuple/dict.
+  * Use the token/``reset`` pattern, not a manual pop — ``reset(token)`` restores the exact
+    prior state even when tasks branch.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import TYPE_CHECKING
+from urllib.parse import quote, unquote
+
+from log_foundry.ids import format_traceparent
+
+if TYPE_CHECKING:
+    from log_foundry.model import Span
+
+__all__ = [
+    "current_span",
+    "push_span",
+    "pop_span",
+    "get_baggage",
+    "set_baggage",
+    "current_traceparent",
+    "current_trace_context",
+    "current_baggage_header",
+]
+
+_span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
+    "log_foundry_span_stack", default=()
+)
+_baggage: contextvars.ContextVar[dict[str, object]] = contextvars.ContextVar(
+    "log_foundry_baggage", default={}
+)
+# An inbound trace context adopted via ``continue_trace`` (SPEC-014), applied by ``_open_span``
+# to the next *root* span. A ContextVar for the same reason as the two above: it is then correct
+# under threads and asyncio for free, and a task that adopts a context cannot leak it to siblings.
+_adopted: contextvars.ContextVar[tuple[str, str | None] | None] = contextvars.ContextVar(
+    "log_foundry_adopted_context", default=None
+)
+
+# W3C suggests 8192 bytes for the whole `baggage` header. Bounded on the way in so a hostile or
+# runaway header cannot inflate every subsequent event emitted by this process.
+BAGGAGE_MAX_BYTES = 8192
+
+
+def current_span() -> Span | None:
+    """Return the innermost active span, or ``None`` when no span is active."""
+    stack = _span_stack.get()
+    return stack[-1] if stack else None
+
+
+def push_span(span: Span) -> contextvars.Token[tuple[Span, ...]]:
+    """Push ``span`` onto the stack; return a token to hand back to :func:`pop_span`."""
+    return _span_stack.set((*_span_stack.get(), span))
+
+
+def pop_span(token: contextvars.Token[tuple[Span, ...]]) -> None:
+    """Restore the span stack to its state before the matching :func:`push_span`."""
+    _span_stack.reset(token)
+
+
+def get_baggage() -> dict[str, object]:
+    """Return the current trace's baggage (do not mutate the returned dict in place)."""
+    return _baggage.get()
+
+
+def set_baggage(**kv: object) -> None:
+    """Merge key/values into the current trace's baggage (replaces with a new dict)."""
+    _baggage.set({**_baggage.get(), **kv})
+
+
+# -- adopted inbound context (SPEC-014) --------------------------------------------------
+
+
+def get_adopted_context() -> tuple[str, str | None] | None:
+    """Return the adopted ``(trace_id, parent_span_id)``, or ``None`` if none was adopted."""
+    return _adopted.get()
+
+
+def set_adopted_context(trace_id: str, parent_span_id: str | None) -> None:
+    """Record an inbound trace context for the next root span opened in this context."""
+    _adopted.set((trace_id, parent_span_id))
+
+
+# -- the producer side: publish where this process is ------------------------------------
+
+
+def current_traceparent() -> str | None:
+    """Return the current span as a W3C ``traceparent`` string, or ``None`` if none is active."""
+    span = current_span()
+    return format_traceparent(span.trace_id, span.span_id) if span else None
+
+
+def current_trace_context() -> tuple[str, str] | None:
+    """Return ``(trace_id, span_id)`` for the current span, or ``None`` if none is active.
+
+    For callers who would rather move two fields than a formatted string — a Step Functions
+    payload, a queue message attribute. It exists so nobody is pushed into
+    :func:`current_span`, which is internal and hands back a mutable :class:`~.model.Span`.
+    """
+    span = current_span()
+    return (span.trace_id, span.span_id) if span else None
+
+
+# -- the W3C `baggage` header codec ------------------------------------------------------
+
+
+def current_baggage_header() -> str:
+    """Return the current baggage in W3C ``baggage`` header format (``""`` when empty).
+
+    The baggage store is ``dict[str, object]`` but the wire format is text, so **non-string
+    values are serialized with ``str()``** — put a dict in baggage and it arrives at the next
+    process as its repr, not as a dict. Keys and values are percent-encoded, so a value
+    containing ``,``, ``=`` or non-ASCII round-trips through :func:`parse_baggage_header`.
+    """
+    return format_baggage_header(get_baggage())
+
+
+def format_baggage_header(baggage: dict[str, object]) -> str:
+    """Serialize a baggage mapping to the W3C ``key1=value1,key2=value2`` format."""
+    # safe="" so the separators themselves (`,` `=` `;`) are encoded rather than corrupting the
+    # framing — the whole reason a value containing a comma can survive the hop.
+    return ",".join(f"{quote(k, safe='')}={quote(str(v), safe='')}" for k, v in baggage.items())
+
+
+def parse_baggage_header(header: object) -> dict[str, object] | None:
+    """Parse a W3C ``baggage`` header into a mapping, or ``None`` if it is unusable.
+
+    Total, like the ``traceparent`` parser: the header arrives from outside the process. Returns
+    ``None`` for a non-string, an empty header, one over :data:`BAGGAGE_MAX_BYTES`, or a
+    malformed member — never a partial parse, which would silently drop correlating fields.
+    """
+    if not isinstance(header, str) or not header.strip():
+        return None
+    if len(header.encode("utf-8", "replace")) > BAGGAGE_MAX_BYTES:
+        return None
+    parsed: dict[str, object] = {}
+    for member in header.split(","):
+        # W3C allows per-member properties after a `;` (e.g. `k=v;metadata`). Nothing here
+        # consumes them, so they are dropped rather than treated as part of the value.
+        entry = member.split(";", 1)[0].strip()
+        if not entry:
+            continue
+        key, sep, value = entry.partition("=")
+        if not sep:
+            return None
+        key = unquote(key.strip())
+        if not key:
+            return None
+        parsed[key] = unquote(value.strip())
+    return parsed or None