log-foundry 0.10.2.dev129__tar.gz → 1.0.0__tar.gz

{log_foundry-0.10.2.dev129 → log_foundry-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev129
+Version: 1.0.0
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -578,7 +578,8 @@ nothing.
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
 call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
 `SinkDeliveryError`, `SinkLosses`, `read_losses` and `flush_sink` — the last two being the probes
-a wrapper sink needs to ask a child for its losses and to push its client-side buffer. The
+a wrapper sink needs to ask a child for its losses and to push its client-side buffer — plus the
+two default bounds, `DEFAULT_SHUTDOWN_TIMEOUT` and `DEFAULT_SWAP_TIMEOUT`. The
 **concrete sinks** are not exported, so import each from its own module, e.g.
 `from log_foundry.sinks.sqs import SQSSink`.
 
@@ -892,8 +893,8 @@ disconnected, so a sustained outage moves `health().failed_batches` instead of b
 | `KafkaSink` | `log_foundry.sinks.kafka` | `kafka` | `KafkaSink(topic, *, flush_timeout=10.0, bootstrap_servers="…", key_field="trace_id", producer_config=None)` — `producer_config` is merged **beneath** the sink's own keys, so it reaches `message.timeout.ms` and friends without displacing `bootstrap.servers`; passing it with `producer=` is a `ValueError` |
 | `RedisStreamsSink` | `log_foundry.sinks.redis` | `redis` | `RedisStreamsSink(stream, *, url=None, maxlen=None)` — `XADD`. `maxlen` caps the stream (`approximate=True`); trimming happens **at Redis**, after delivery, so it is invisible to `health()` — which is why the default is unbounded |
 | `RedisListSink` | `log_foundry.sinks.redis` | `redis` | `RedisListSink(key, *, url=None, maxlen=None)` — `RPUSH` + `LTRIM` to the newest `maxlen`; same destination-side trimming caveat |
-| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None)` — persistent messages |
-| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
+| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None, blocked_connection_timeout=None, socket_timeout=None, stack_timeout=None)` — persistent messages; `pika` leaves `blocked_connection_timeout` unset, so a broker under a memory or disk alarm blocks every publish indefinitely — the sink applies `DEFAULT_BLOCKED_CONNECTION_TIMEOUT` (30 s) unless the URL's query names one, and an explicit keyword overrides the URL. **Read from `pika` 1.4.4 and not executed against a broker** — verify it against yours |
+| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — a non-positive `max_reconnect_attempts` is a `ValueError` at construction, since `nats-py` retires a server from its pool only under `max_reconnect_attempts > 0` and a non-positive value therefore never returns; `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
 | `GooglePubSubSink` | `log_foundry.sinks.pubsub` | `gcp-pubsub` | `GooglePubSubSink(topic)` |
 | `AzureEventHubsSink` | `log_foundry.sinks.eventhubs` | `azure-eventhubs` | `AzureEventHubsSink(*, connection_str="…", eventhub=None)` |
 
@@ -908,9 +909,9 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
-| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…")` |
+| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…", socket_timeout=None, server_selection_timeout=None)` — `pymongo`'s `socketTimeoutMS` default is `None`, so a read that never returns holds the drain thread; the sink applies `DEFAULT_SOCKET_TIMEOUT` (30 s) only when neither the keyword nor the URI query names one |
 | `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False, connect_timeout=5)` — JSONB `event` column + extracted columns. Reconnects an **owned** connection the server has closed; a `connection=` you inject is never reopened. `connect_timeout` is passed to libpq explicitly, so it **overrides** any `connect_timeout` in your DSN |
-| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False)` — MergeTree, columnar insert |
+| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False, chunk_size=1000, send_receive_timeout=None)` — MergeTree, columnar insert; the driver's own 300 s `send_receive_timeout` is finite so it is left alone, and forwarded only when you set it |
 
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set
 it `True` for an idempotent `CREATE TABLE IF NOT EXISTS` convenience.
@@ -1103,9 +1104,11 @@ reported. They aggregate different failure populations — one can mean the dest
 data; the other never the destination — the data, or no drain thread at all (SPEC-050) — so a
 single number would hide which fix applies.
 
-`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no worker
-exists yet, or when the configured sink reports nothing (`losses()` is optional, and a sink whose
-`losses()` raises reports `None` too). Note the two `dropped` fields count
+`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no sink has
+been configured at all, and `None` when the configured sink reports nothing (`losses()` is
+optional, and a sink whose `losses()` raises reports `None` too). It is **not** `None` merely
+because no worker exists: since SPEC-054 it is answered
+from the configuration, so it reports on the orphan path too. Note the two `dropped` fields count
 different things: the worker's is backpressure at *its* queue, the sink's is an event that never
 reached the wire. They are separate because the remedies do not overlap — and `sink.dropped` is
 itself two causes, which is why the diagnostic line matters. Most sinks drop only what can never
@@ -1133,10 +1136,13 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
-`retired`, `orphan_lost` and `in_span_lost` are the fields reported for a process that has **no
-worker at all**. A program that only ever calls `info()`/`error()` outside a span emits
-synchronously and builds no background worker, so the rest describe something that does not exist
-and read zero — which is why that path needs counters of its own. Until it had them, such a process
+**Six of the twelve fields report for a process that has no worker at all** — `sink`, `retired`,
+`closing_sinks`, `inherited_sink`, `orphan_lost` and `in_span_lost`. That set is not a list to
+maintain by hand: it is exactly the fields in `_lifecycle`'s `Health(...)` assembly that are *not*
+guarded by `counters is None`, and re-reading that call is how to check it. A program that only
+ever calls `info()`/`error()` outside a span emits synchronously and builds no background worker,
+so the other six describe something that does not exist and read their empty value — zero for the
+five counters, `None` for `stopped_reason` — which is why that path needs counters of its own. Until it had them, such a process
 reported `queued=0 dropped=0 failed_batches=0 stopped_reason=None` over total, permanent loss, and
 the only thing that said otherwise was a line on stderr. Its
 `shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
@@ -1411,8 +1417,8 @@ failure lands on whoever caused it rather than on a shared branch. Contributors
 with `scripts/spec-lint.sh`, before pushing.
 
 On a push to `main` the full `ci.yml` matrix still runs, but as the first job of
-[`release.yml`](.github/workflows/release.yml), which `uses:` this same workflow before it is
-allowed to publish — so on main the checks are listed under the *Release* workflow, named
+[`release.yml`](.github/workflows/release.yml), which `uses:` this same workflow before it would
+be allowed to publish — so on main the checks are listed under the *Release* workflow, named
 `test / test (py3.12)` and `test / test (py3.13)`. `ci.yml` deliberately carries no `push`
 trigger of its own; it had one, and the result was that every merge ran the identical matrix
 twice. A `v*` tag is gated the same way, by that same reusable call.
@@ -1469,12 +1475,14 @@ sdist and a wheel:
 
 | Trigger | Version built | Published to PyPI as |
 |---|---|---|
-| merge to `main` | `X.Y.Z.devN` | dev pre-release |
+| merge to `main` | `X.Y.Z.devN` | **nothing, for now** — `publish-dev` is disabled |
 | push tag `vX.Y.Z` | `X.Y.Z` | stable release |
 
-Dev pre-releases keep the upload path exercised on every merge, so a real release is never the
-first time it runs. `pip install log-foundry` still resolves to the latest **stable** version —
-pip ignores pre-releases unless you pass `--pre`.
+Dev pre-releases **kept** the upload path exercised on every merge, so a real release was never
+the first time it ran. That property is suspended along with the job: the next `vX.Y.Z` tag is
+the first attempt at the upload path since `publish-dev` was disabled. `pip install log-foundry`
+resolves to the latest **stable** version either way — pip ignores pre-releases unless you pass
+`--pre`.
 
 Cutting a release is one tag:
 
@@ -1491,7 +1499,8 @@ the tagged commit are not seen. A release body cannot be amended once published
 repository has immutable releases — so check the file is there and named for the tag before
 pushing it. [`docs/release-notes/`](docs/release-notes/) holds the ones written so far, and
 [`docs/spec-delivery/RELEASES.md`](docs/spec-delivery/RELEASES.md) records which specs each
-released version carried.
+version carried — its top row is written in the commit that version's tag is cut from, so it can
+name a tag that does not exist yet.
 
 Uploads authenticate with PyPI [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
 (OIDC) through the `pypi` GitHub Environment — there is no API token stored in the repository.

{log_foundry-0.10.2.dev129 → log_foundry-1.0.0}/README.md

@@ -527,7 +527,8 @@ nothing.
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
 call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
 `SinkDeliveryError`, `SinkLosses`, `read_losses` and `flush_sink` — the last two being the probes
-a wrapper sink needs to ask a child for its losses and to push its client-side buffer. The
+a wrapper sink needs to ask a child for its losses and to push its client-side buffer — plus the
+two default bounds, `DEFAULT_SHUTDOWN_TIMEOUT` and `DEFAULT_SWAP_TIMEOUT`. The
 **concrete sinks** are not exported, so import each from its own module, e.g.
 `from log_foundry.sinks.sqs import SQSSink`.
 
@@ -841,8 +842,8 @@ disconnected, so a sustained outage moves `health().failed_batches` instead of b
 | `KafkaSink` | `log_foundry.sinks.kafka` | `kafka` | `KafkaSink(topic, *, flush_timeout=10.0, bootstrap_servers="…", key_field="trace_id", producer_config=None)` — `producer_config` is merged **beneath** the sink's own keys, so it reaches `message.timeout.ms` and friends without displacing `bootstrap.servers`; passing it with `producer=` is a `ValueError` |
 | `RedisStreamsSink` | `log_foundry.sinks.redis` | `redis` | `RedisStreamsSink(stream, *, url=None, maxlen=None)` — `XADD`. `maxlen` caps the stream (`approximate=True`); trimming happens **at Redis**, after delivery, so it is invisible to `health()` — which is why the default is unbounded |
 | `RedisListSink` | `log_foundry.sinks.redis` | `redis` | `RedisListSink(key, *, url=None, maxlen=None)` — `RPUSH` + `LTRIM` to the newest `maxlen`; same destination-side trimming caveat |
-| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None)` — persistent messages |
-| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
+| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None, blocked_connection_timeout=None, socket_timeout=None, stack_timeout=None)` — persistent messages; `pika` leaves `blocked_connection_timeout` unset, so a broker under a memory or disk alarm blocks every publish indefinitely — the sink applies `DEFAULT_BLOCKED_CONNECTION_TIMEOUT` (30 s) unless the URL's query names one, and an explicit keyword overrides the URL. **Read from `pika` 1.4.4 and not executed against a broker** — verify it against yours |
+| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — a non-positive `max_reconnect_attempts` is a `ValueError` at construction, since `nats-py` retires a server from its pool only under `max_reconnect_attempts > 0` and a non-positive value therefore never returns; `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
 | `GooglePubSubSink` | `log_foundry.sinks.pubsub` | `gcp-pubsub` | `GooglePubSubSink(topic)` |
 | `AzureEventHubsSink` | `log_foundry.sinks.eventhubs` | `azure-eventhubs` | `AzureEventHubsSink(*, connection_str="…", eventhub=None)` |
 
@@ -857,9 +858,9 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
-| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…")` |
+| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…", socket_timeout=None, server_selection_timeout=None)` — `pymongo`'s `socketTimeoutMS` default is `None`, so a read that never returns holds the drain thread; the sink applies `DEFAULT_SOCKET_TIMEOUT` (30 s) only when neither the keyword nor the URI query names one |
 | `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False, connect_timeout=5)` — JSONB `event` column + extracted columns. Reconnects an **owned** connection the server has closed; a `connection=` you inject is never reopened. `connect_timeout` is passed to libpq explicitly, so it **overrides** any `connect_timeout` in your DSN |
-| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False)` — MergeTree, columnar insert |
+| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False, chunk_size=1000, send_receive_timeout=None)` — MergeTree, columnar insert; the driver's own 300 s `send_receive_timeout` is finite so it is left alone, and forwarded only when you set it |
 
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set
 it `True` for an idempotent `CREATE TABLE IF NOT EXISTS` convenience.
@@ -1052,9 +1053,11 @@ reported. They aggregate different failure populations — one can mean the dest
 data; the other never the destination — the data, or no drain thread at all (SPEC-050) — so a
 single number would hide which fix applies.
 
-`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no worker
-exists yet, or when the configured sink reports nothing (`losses()` is optional, and a sink whose
-`losses()` raises reports `None` too). Note the two `dropped` fields count
+`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no sink has
+been configured at all, and `None` when the configured sink reports nothing (`losses()` is
+optional, and a sink whose `losses()` raises reports `None` too). It is **not** `None` merely
+because no worker exists: since SPEC-054 it is answered
+from the configuration, so it reports on the orphan path too. Note the two `dropped` fields count
 different things: the worker's is backpressure at *its* queue, the sink's is an event that never
 reached the wire. They are separate because the remedies do not overlap — and `sink.dropped` is
 itself two causes, which is why the diagnostic line matters. Most sinks drop only what can never
@@ -1082,10 +1085,13 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
-`retired`, `orphan_lost` and `in_span_lost` are the fields reported for a process that has **no
-worker at all**. A program that only ever calls `info()`/`error()` outside a span emits
-synchronously and builds no background worker, so the rest describe something that does not exist
-and read zero — which is why that path needs counters of its own. Until it had them, such a process
+**Six of the twelve fields report for a process that has no worker at all** — `sink`, `retired`,
+`closing_sinks`, `inherited_sink`, `orphan_lost` and `in_span_lost`. That set is not a list to
+maintain by hand: it is exactly the fields in `_lifecycle`'s `Health(...)` assembly that are *not*
+guarded by `counters is None`, and re-reading that call is how to check it. A program that only
+ever calls `info()`/`error()` outside a span emits synchronously and builds no background worker,
+so the other six describe something that does not exist and read their empty value — zero for the
+five counters, `None` for `stopped_reason` — which is why that path needs counters of its own. Until it had them, such a process
 reported `queued=0 dropped=0 failed_batches=0 stopped_reason=None` over total, permanent loss, and
 the only thing that said otherwise was a line on stderr. Its
 `shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
@@ -1360,8 +1366,8 @@ failure lands on whoever caused it rather than on a shared branch. Contributors
 with `scripts/spec-lint.sh`, before pushing.
 
 On a push to `main` the full `ci.yml` matrix still runs, but as the first job of
-[`release.yml`](.github/workflows/release.yml), which `uses:` this same workflow before it is
-allowed to publish — so on main the checks are listed under the *Release* workflow, named
+[`release.yml`](.github/workflows/release.yml), which `uses:` this same workflow before it would
+be allowed to publish — so on main the checks are listed under the *Release* workflow, named
 `test / test (py3.12)` and `test / test (py3.13)`. `ci.yml` deliberately carries no `push`
 trigger of its own; it had one, and the result was that every merge ran the identical matrix
 twice. A `v*` tag is gated the same way, by that same reusable call.
@@ -1418,12 +1424,14 @@ sdist and a wheel:
 
 | Trigger | Version built | Published to PyPI as |
 |---|---|---|
-| merge to `main` | `X.Y.Z.devN` | dev pre-release |
+| merge to `main` | `X.Y.Z.devN` | **nothing, for now** — `publish-dev` is disabled |
 | push tag `vX.Y.Z` | `X.Y.Z` | stable release |
 
-Dev pre-releases keep the upload path exercised on every merge, so a real release is never the
-first time it runs. `pip install log-foundry` still resolves to the latest **stable** version —
-pip ignores pre-releases unless you pass `--pre`.
+Dev pre-releases **kept** the upload path exercised on every merge, so a real release was never
+the first time it ran. That property is suspended along with the job: the next `vX.Y.Z` tag is
+the first attempt at the upload path since `publish-dev` was disabled. `pip install log-foundry`
+resolves to the latest **stable** version either way — pip ignores pre-releases unless you pass
+`--pre`.
 
 Cutting a release is one tag:
 
@@ -1440,7 +1448,8 @@ the tagged commit are not seen. A release body cannot be amended once published
 repository has immutable releases — so check the file is there and named for the tag before
 pushing it. [`docs/release-notes/`](docs/release-notes/) holds the ones written so far, and
 [`docs/spec-delivery/RELEASES.md`](docs/spec-delivery/RELEASES.md) records which specs each
-released version carried.
+version carried — its top row is written in the commit that version's tag is cut from, so it can
+name a tag that does not exist yet.
 
 Uploads authenticate with PyPI [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
 (OIDC) through the `pypi` GitHub Environment — there is no API token stored in the repository.

{log_foundry-0.10.2.dev129 → log_foundry-1.0.0}/pyproject.toml

@@ -30,9 +30,11 @@ dependencies = [
 classifiers = [
     # Asserts what the NEXT STABLE TAG will be, not what the current version is. Safe only
     # because PyPI's default project page renders the latest stable release, which is still
-    # `v0.10.1` and carries none of this; the artifacts carrying it in the meantime are the
-    # `.devN` pre-releases that SECURITY.md declares unsupported and that `pip install` does
-    # not select. Their own per-version pages DO show it, so this is narrow, not free.
+    # `v0.10.1` and carries none of this. The artifacts that carried it in the meantime were the
+    # `.devN` pre-releases SECURITY.md declares unsupported and `pip install` does not select;
+    # their own per-version pages DO show it, so this was narrow rather than free. With
+    # `publish-dev` disabled no new artifact carries it at all, which narrows the exposure
+    # further — the claim is not more true, it just reaches nobody until the next tag.
     # Revisit if the next stable tag is not `v1.0.0`: README still says three public shapes
     # change once, before the API is frozen, and Production/Stable on the default page would
     # then contradict it.
@@ -74,7 +76,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev129"
+version = "1.0.0"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"