You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by "mlevkov (via GitHub)" <gi...@apache.org> on 2026/08/02 08:32:46 UTC

[PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

mlevkov opened a new pull request, #3798:
URL: https://github.com/apache/iggy/pull/3798

   Implements the webhook gateway accepted in #3039. Iggy currently has no way to receive a webhook; every provider that pushes events over HTTP needs a separate service in front whose only job is to accept a POST and republish it. This connector removes that hop.
   
   ## Shape
   
   One plugin `.so` is loaded once regardless of how many `[[source]]` entries reference it, so the listener lives in a process-global registry keyed by listen address rather than on any single instance. The first `open()` binds the public and admin ports; later opens validate their body limit, admin address, management token and instance name against the running listener before joining; the last `close()` releases both ports, which the runtime's stop-then-start restart flow depends on. A single port can therefore serve many providers, each routed to its own topic.
   
   - `POST /topics/{topic_path}` — named path, one per instance, guarded by an optional bearer token
   - `POST /e/{endpoint_id}` — secret path, 128 bits in the URL itself, with optional per-endpoint bearer or HMAC on top
   
   Requests resolve against an `ArcSwap` route table rebuilt whole on every control-plane change, so one atomic load yields both the endpoint's auth rules and the destination bridge. HMAC is verified over the raw body in constant time. Revoked endpoints answer 404 alongside paths that never existed, so a leaked URL cannot be used to confirm it was once live.
   
   Endpoints can be registered, re-keyed and revoked at runtime through a token-guarded API on the admin listener (absent entirely when no token is configured). Those endpoints ride the SDK's `ConnectorState`, and revocation writes a tombstone that outranks TOML on restore, so a stale config file cannot resurrect an endpoint an operator revoked.
   
   ## Delivery semantics
   
   Best-effort in both directions, and the README leads with it rather than burying it. HTTP 200 means accepted into an in-memory buffer, not durably stored; both the loss and duplicate windows are enumerated with what mitigates each. A full bridge answers 429 with `Retry-After` rather than blocking.
   
   **Depends on #3795 for the full backpressure story.** The bridge is bounded today, so 429 fires on an arrival burst the poll loop cannot keep up with. What is missing is the coupling: until the bounded runtime forwarding channel lands, `poll()` drains into an unbounded channel, so a slow Iggy does not propagate back into 429. The README documents this rather than implying the chain is complete.
   
   State is attached only to an empty batch. The runtime saves state solely on the success branch of the Iggy send, and an empty send always succeeds, so a management mutation cannot be lost to an unrelated send failure.
   
   ## Deviations from the design doc, all deliberate
   
   - **`topic_path` and `instance_name` are explicit config fields.** Only `plugin_config` crosses the FFI, so the plugin cannot see its connector key or its `[[streams]]` entry. Same resolution the design already accepted for the named path.
   - **The 503 "instance closing" row collapses into 404.** Deregistration is atomic under the registry lock, so no observable window exists. 503 survives on `GET /health` when no instance is joined.
   - **Stripe and Twilio HMAC are not supported.** This validator takes a hex digest of the body behind a fixed prefix, which covers GitHub and most generic partner webhooks. Stripe signs `{timestamp}.{body}` behind a compound header and Twilio signs URL plus sorted params as base64. The design's example config showed Stripe working; it would not have. Documented with the forward-and-verify-downstream workaround, and the shipped example uses bearer instead.
   - **`schema = "raw"` is mandatory** and now stated as such — the connector always produces raw bodies, and a JSON encoder rejects every message.
   
   ## Testing
   
   110 unit tests and 5 integration tests. The integration suite needs no containers, since the connector is itself the HTTP server and the test client is the webhook sender: it covers a signed POST reaching Iggy byte-for-byte with headers intact, two instances sharing one listener, the register/POST/revoke flow, a dynamic endpoint with its secret surviving a connector restart, and a revoked *static* endpoint staying dead across a restart that re-reads the TOML still declaring it.
   
   No integration test for 429 under saturation: with a healthy Iggy the poll loop drains the bridge continuously, so provoking a full bridge from outside races the drain. Two unit tests cover it deterministically instead.
   
   ## Verification
   
   `cargo fmt`, `cargo sort --check --no-format --workspace`, `cargo clippy --all-features --all-targets -- -D warnings` (connector and integration), `cargo test`, `taplo fmt --check`, `hawkeye check`, markdownlint, and the trailing-whitespace/newline scripts all pass locally.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5160404774

   Pushed a follow-up commit closing the coverage gaps worth closing. Kept it as a
   separate commit rather than amending, so the delta is reviewable on its own.
   
   Patch coverage was 94.52% (2847 hits / 131 misses / 34 partials). Reading the
   per-line report rather than the percentage turned up one gap that mattered:
   
   **Both existing management auth tests reached only `GET /admin/endpoints`.**
   Coverage regions are per call site, so `denied()` looked fully covered while the
   guard inside `register_endpoint`, `rotate_secret`, `revoke_endpoint`, and
   `get_endpoint` had never taken its rejection branch. Deleting the check from
   `revoke_endpoint` left the suite green — it now fails with 204 instead of 401.
   
   Also newly pinned: `republish_or_close` answering 500 rather than reporting a
   revoke that never reached the route table; the endpoint-id route conflict keeping
   the id to an 8-char prefix in its message; the `hmac_algorithm()` mapping; a
   revoked *dynamic* endpoint's tombstone surviving restore with no static
   counterpart; and the two `message_headers` drop branches.
   
   Every new test was mutation-checked — each was confirmed to fail against a
   deliberate break of the behaviour it claims to pin, rather than assumed to work
   because it passed.
   
   One production line changed: `ServerState::new` is now `pub(crate)` so the
   management tests can build a listener-less state and provoke the republish
   failure. The other 328 added lines are tests.
   
   Deliberately left uncovered, and why:
   
   - `SharedServer::shutdown`'s abort branch — needs a connection wedged past the
     5s timeout, so pinning it costs a 5s+ unit test.
   - The bind-failure and draining-listener-join races.
   - `Metrics::encode`'s encoder-failure branch.
   - ~30 of the remaining missed lines are **tracing-macro arguments**. `tracing`
     skips formatting when no subscriber enables the level, so those regions never
     execute under `cargo test` even where the surrounding branch is fully
     exercised. Installing a subscriber would raise the number without testing
     anything, so I left it alone — worth knowing when reading the residual figure.
   
   `Metrics::default` and `EndpointRegistry::is_empty` were uncovered and have no
   callers, but they can't be deleted: `clippy::new_without_default` and
   `clippy::len_without_is_empty` require them. Covered with one assertion each.
   
   Full local gate green (fmt, sort, workspace clippy `-D warnings`, build, 124 unit
   tests, 5 http_source integration tests, taplo, hawkeye, typos, trailing
   whitespace/newline).
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434307121

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5442517178

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434594103

   One more commit, `4a52b301c`, and it is documentation rather than code. Flagging it because it touches shared guidance, not just this connector.
   
   `.claude/skills/connector-source/SKILL.md` carried two rules this connector knowingly breaks, and leaving them contradicted means every future reviewer re-litigates whether the connector is wrong.
   
   One of them was simply incorrect: *"Always return state in every `ProducedMessages`, including empty polls."* The runtime saves state only on the success branch of the Iggy send, so state riding a batch of messages is skipped whenever that send fails, while the source has already cleared its dirty flag and marked its records submitted. The rule now says to return state on a batch whose send cannot fail, and names both shapes: stage-and-apply through `on_batch_result` for a cursor source, an empty batch for a control-plane record like an endpoint registry.
   
   The other earned its keep and stays. The ban on long-running plugin tasks exists because orphans survive `close()`, which is exactly the `setup_source_producer` failure we discussed. It now records the sanctioned exception rather than reading as violated: a source that listens rather than polls has to own its listener, and only with an explicit shutdown in the last `close()` that awaits its tasks before returning.
   
   `on_batch_result` also appeared nowhere in that skill despite being the whole delivery contract since #3855, so the one-batch-in-flight rule, the five-NACK stop that skips `close()`, and the default no-op that silently loses data for any source advancing a cursor in `poll()` are now written down. That last part is the same ground as #3898's rescope, so if you delete the default the skill is already pointing the right way.
   
   The testing skill gained the practice these rounds proved out: break the behaviour a test names and watch it fail before trusting it. That is how the two tests that could not fail were found, including one asserting against gauges the metrics encoder rebuilds on every scrape.
   
   Happy to split this into its own PR if you would rather keep #3798 to the connector.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5365057974

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5549880004

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5442513087

   All six addressed in `9c530f530`. Four were consequences of my own last round, which is a fair hit rate for changes made that late.
   
   **`routes.rs:209` is the one that mattered.** You are right that `build` inserts revoked and expired endpoints, and that is deliberate so a leaked id resolves to a 404 attributed to its owner rather than to `unrouted`. So the emptiness check I added for the readiness gate asked whether anything had ever been inserted, and an instance with everything revoked read as routable while it would refuse every request. It is now `serves_anything(now)`, which asks whether any path would accept a request right now, with a test that revokes the only endpoint and expects 503. Mutation-checked: relaxing the predicate fails that test.
   
   **`metrics.rs:149`** is the sharper catch. That branch exists precisely so a dead bridge is not filed as backpressure, and then it filed it there anyway. It has its own `http_source_rejected_disconnected_total` now, since a 429 tells a sender to retry and a bridge with no receiver never will. README table updated with a note column for both.
   
   **`server.rs:218`** was a plain mistake in the `ArcSwap` unification: `Published` landed between `ServerState`'s doc line and the struct and took both the comment and the `#[derive(Debug)]`. Moved back, and `Published` derives `Debug, Default`.
   
   **`routes.rs:93`** was a comment claiming a guard that cannot work. You are right that msgpack compact writes the struct as a positional array, so a record can only ever be short from the end and `auth_type` sits second of eight. The comment now says the no-default is there for symmetry and that `state`, being last, is the one actually doing the work.
   
   **README:115** was stale the moment I moved the named-path auth ahead of the body read, and I did not update the row. It now separates the two paths: `/e/{id}` keeps the `Bytes` extractor and reads before authenticating because HMAC needs the raw body, while the named path checks the bearer first and applies the cap by hand afterwards.
   
   **README:166** now names both sources of 503, `/health` and a POST whose bridge has no receiver, with the two distinct bodies.
   
   While in there I found two more of my own: the backpressure section still said the coupling was missing "until #3795 lands", and #3795 is closed. #3855 supplied that coupling instead, since the SDK keeps one batch in flight and will not poll again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop and the bridge fills into a 429. The `buffer_capacity` row said the same thing and is corrected too.
   
   148 unit tests, six integration tests against a real server and runtime, all gates green.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5442513354

   /ready


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "numinnex (via GitHub)" <gi...@apache.org>.
numinnex commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3966188210


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,

Review Comment:
   `#[serde(default)]` here undoes one level up what `routes.rs:96-99` withholds `default` from `auth_type`/`state` to achieve. `rmp_serde::from_slice` also never checks that the decode consumed the blob (`decode.rs:1171-1188`, no `end()`), so any structurally valid shortening decodes `Ok` with zero tombstones, and revoked static endpoints return live from TOML with their secrets.
   
   Reproduced: `0x91`->`0x90` on byte 0, `[0x90]`, and `0x81`->`0x80` on byte 1 each give `Ok, endpoints = 0`. Dropping `default` fixes the first two, a trailing-byte check fixes the first and third, and `[0x91,0x80]` survives both.
   
   Complete fix is framing outside the serde struct: non-defaulted `{version, endpoint_count, endpoints}`, decoded through `Deserializer::new(Cursor::new(&blob))` asserting `position() == blob.len()`, then verifying the count. `from_slice` cannot be patched in place; `position()` exists only on the `ReadReader<Cursor<_>>` flavour.
   
   Better here than as a follow-up: the crate is new and `publish = false`, so no state file exists yet. Post-release the same change is a fail-closed boot for every instance unless a legacy-shape fallback goes in, and that fallback reopens the class for a release.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();

Review Comment:
   Second route into the same fail-open, and this one needs no corruption. `FileStateProvider::load` maps a zero-length file to `Ok(None)` (`core/connectors/runtime/src/state.rs:195-198`), so `had_state` is false here and the `Err` guard below never fires. The instance then serves its TOML endpoints with every tombstone gone, logging only `info!` "with no persisted registry".
   
   An operator truncating the file to clear one tombstone lands here, and `README.md:341` reads as though truncating and deleting are the same act. The two backends also disagree on this byte pattern: `state/http.rs:255-257` treats a zero-length body as valid state.
   
   The plugin cannot tell first boot from truncation, so the fix here is a `warn!` when static endpoints exist and no state was presented. Aligning the two providers belongs in the runtime.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)

Review Comment:
   `all(poll_is_live)` cannot separate never-polled from stopped. `join` publishes the instance at `server.rs:120-121` while `last_poll_at` is still 0 (`lib.rs:777`) and `poll_active` is false, so `/health` answers 503 and `/admin/health` "degraded" for every healthy sibling on the listener until this instance's first poll.
   
   That window is a full `setup_source_producer`: `init_source` runs at `runtime/src/source.rs:200`, then Iggy login plus stream and topic ensure with retries at `:229`, then the poll task spawns. So restarting one instance drains its siblings from the load balancer, and on boot the window spans other connectors' producer setup too.
   
   Publishing an instance's routes on its first `poll()` rather than in `join()` fixes it. A boot grace period does not: it reopens answering 200 to the balancer while nothing drains the bridge.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;

Review Comment:
   Neither this `InitError` nor any `validate()` message reaches an operator. `SourceContainer::open` discards the `Err` without logging it (`core/connectors/sdk/src/source.rs:177-180`, returns only `0`/`1`), and `init_source` substitutes `"Plugin initialization failed (ID: {id})"` (`core/connectors/runtime/src/source.rs:300`), which is what lands in `last_error`.
   
   So all 16 `validate()` strings, `bind()`'s field hint, `ensure_compatible`'s three messages, `RouteConflict::Display` and the restore refusal are dead text, and with them the `last_error` claims at `state.rs:84`, `lib.rs:707-709` and `README.md:218-222,262`.
   
   `error!` the message here before returning `Err` rescues all of it. The log callback is installed at `sdk/src/source.rs:150-153` before `factory`, so a plugin-side `error!` does reach the runtime log today.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let now_seconds = unix_now_seconds();
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // The same rule registration applies, asked here and only warned
+            // about. `restore` failing is a hard `open()` failure, so refusing
+            // would take a whole instance down over one stored value an
+            // operator cannot edit without the state file.
+            //
+            // Asked rather than re-derived, because the two hand-written checks
+            // that used to live here had already drifted from it: they covered
+            // the ceilings and a malformed `hmac_header`, and silently skipped
+            // an endpoint advertising auth with no usable secret. That one
+            // restores active, reads active on the admin API, and rejects every
+            // request forever, which is fail-closed and completely silent.
+            //
+            // `Existing`, so a stored `expires_at` that has merely passed is not
+            // reported as a fault: the endpoint answers 404 on its own path and
+            // that is the documented behaviour.
+            //
+            // Skipped for an endpoint whose expiry has already passed. Its
+            // secret is cleared below, so on the next restart this rule would
+            // report `MissingSecret` and blame the credential for a refusal
+            // that expiry already explains.
+            if !revoked
+                && !endpoint.is_expired(now_seconds)
+                && let Err(reason) = admit_endpoint(
+                    endpoint.auth_type,
+                    &endpoint.auth_secret,
+                    &endpoint.hmac_header,
+                    &endpoint.hmac_prefix,
+                    endpoint.expires_at,
+                    Admission::Existing,
+                )
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id}: {reason}; it is served but every request to it will be refused until it is re-registered",
+                    endpoint_id.log_prefix()
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    // The map was seeded from TOML, so Occupied means TOML
+                    // still declares this id: the tombstone is static whatever
+                    // the state file says. Taking the persisted `origin`
+                    // verbatim let a `Dynamic` tombstone be the entry that
+                    // outranks a live TOML block, and `reclaimable_tombstones`
+                    // evicts exactly the dynamic ones, so the next restart
+                    // served that endpoint and its secret again. Reclamation is
+                    // only safe because a static tombstone is never eligible.
+                    endpoint.origin = EndpointOrigin::Static;
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    // A static entry reaches this arm only when TOML no longer
+                    // declares it. Restoring an active one resurrects an
+                    // endpoint the operator decommissioned by deleting it, and
+                    // `rotate_secret` then refuses it as static and points at a
+                    // TOML entry that is gone, so there is no way back. Its
+                    // tombstone still has to survive: re-adding the id to TOML
+                    // later must not undo a revocation.
+                    if !revoked && endpoint.origin == EndpointOrigin::Static {
+                        dropped_static += 1;
+                        continue;
+                    }
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        // Same reasoning as `revoke()`: the handler answers 404 on an expired
+        // endpoint before `authorize()` runs, so its stored secret is already
+        // dead weight, and nothing compacts the registry. Keeping it wrote a
+        // credential the operator can no longer use back to disk on every later
+        // flush, indefinitely, which is exactly what `revoke()` clears the
+        // secret to avoid.
+        //
+        // The endpoint keeps its slot and stays `Active`. Reclaiming it would
+        // make endpoints disappear on a clock condition rather than an operator
+        // action.
+        //
+        // Restore only, deliberately. An endpoint that expires while the
+        // instance is running keeps its stored secret until the next restart,
+        // because clearing it then would need a clock-driven sweep mutating the
+        // registry from `poll()`. `revoke` is what clears it immediately.
+        let mut expired_secrets = 0;
+        for endpoint in endpoints.values_mut() {
+            if endpoint.is_active()
+                && endpoint.is_expired(now_seconds)
+                && endpoint.auth_secret.is_some()
+            {
+                endpoint.auth_secret = None;
+                expired_secrets += 1;
+            }
+        }
+        // The third of the three restore-time faults that get a line of their
+        // own: an expired endpoint is otherwise silent at startup.
+        if expired_secrets > 0 {
+            warn!(
+                "Cleared the stored secret of {expired_secrets} expired endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id}; they keep their slot and answer 404 until re-registered"
+            );
+        }
+
+        // Loud on purpose: these were serving before the restart, and the only
+        // trace of them left is this line.
+        if dropped_static > 0 {
+            warn!(
+                "Dropped {dropped_static} persisted static endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id} that the TOML config no longer declares; they no longer serve"
+            );
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"
+        );
+
+        Ok(EndpointRegistry { endpoints })
+    }
+
+    pub fn endpoints(&self) -> impl Iterator<Item = &Endpoint> {
+        self.endpoints.values()
+    }
+
+    pub fn endpoint(&self, endpoint_id: &str) -> Option<&Endpoint> {
+        self.endpoints.get(endpoint_id)
+    }
+
+    pub fn endpoint_mut(&mut self, endpoint_id: &str) -> Option<&mut Endpoint> {
+        self.endpoints.get_mut(endpoint_id)
+    }
+
+    /// [`Self::try_insert`] for tests that only care whether the registry
+    /// changed.
+    ///
+    /// Test-only on purpose. It collapses `Full` and `Collision` into one
+    /// `false`, so production code reaching for it would drop the distinction
+    /// between a registry at its ceiling and an id that is already taken, and
+    /// answer the caller the same way for both.
+    #[cfg(test)]
+    pub fn insert(&mut self, endpoint: Endpoint) -> bool {
+        self.try_insert(endpoint) == InsertOutcome::Inserted
+    }
+
+    /// Registers a new endpoint, reporting why it was refused.
+    ///
+    /// Nothing evicts tombstones on its own and every mutation clones the whole
+    /// registry, so without a ceiling a caller holding the management token can
+    /// grow the state file and the per-mutation cost without limit. At the
+    /// ceiling the oldest revoked *dynamic* entries are reclaimed first: such an
+    /// endpoint exists only here, so dropping it leaves its path answering 404
+    /// exactly as its tombstone did. A revoked static one is never reclaimed,
+    /// because its tombstone is what outranks a TOML entry that still declares
+    /// it.
+    ///
+    /// Either the whole thing succeeds or nothing is touched, so a refusal
+    /// cannot leave the registry partially reclaimed and arm a flush for it.
+    pub fn try_insert(&mut self, endpoint: Endpoint) -> InsertOutcome {
+        if self.endpoints.contains_key(&endpoint.endpoint_id) {
+            return InsertOutcome::Collision;
+        }
+        if self.endpoints.len() >= MAX_ENDPOINTS {
+            let wanted = self.endpoints.len() - MAX_ENDPOINTS + 1;

Review Comment:
   This is the only place `MAX_ENDPOINTS` is enforced, so it bounds dynamic registration and nothing else. `HttpSourceConfig::validate` does not bound `config.endpoints` and `restore` does not bound the merged map, so TOML or a state file can put the registry arbitrarily above the cap that `README.md:340` states as a per-instance property.
   
   Over the cap the arithmetic compounds: at 15000 entries `wanted` is 5001, so a single registration evicts up to 5001 revoked-dynamic tombstones in one `try_insert`. No resurrection risk, since static tombstones are never eligible, but the audit record goes.
   
   Reject `config.endpoints.len() > MAX_ENDPOINTS` in `validate`, warn rather than fail in `restore`, and report the actual length in the 507 at `management.rs:206`.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,358 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts**, so set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, applied by the handlers rather than an extractor. Routing wins over it: an oversized POST to an unknown or revoked path answers 404 without the body being read. Must match across instances sharing a listener. **Max 67108864**; a larger value fails `open()`. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. **Max 1000000**; a larger value fails `open()`. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. **Max 100000**; a larger value fails `open()`. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie`, because forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. The endpoint keeps its slot, and its stored secret is dropped on the next restart. |
+
+An expired endpoint is not reclaimed. It keeps its `max_endpoints` slot and answers 404, and only revoking it frees the slot.
+
+Its stored secret is a different matter. The connector drops that from the registry on the next restart, because the endpoint is refused before any credential is checked and keeping it would write a credential nobody can use back to the state file on every later flush. That happens at restore only, so an endpoint that expires while the instance is running keeps its secret on disk until it restarts. Revoke it to clear the secret immediately.
+
+Env overrides reach top-level fields only, and only under the local config provider. `IGGY_CONNECTORS_SOURCE_<KEY>_PLUGIN_CONFIG_<FIELD>` sets one field of this table; the suffix is taken whole, so a nested attempt such as `..._ENDPOINTS_0_AUTH_SECRET` becomes the flat key `endpoints_0_auth_secret` and is ignored. Endpoint secrets therefore stay in TOML or go through the management API.
+
+Values are coerced before they are deserialized: `true`/`false` become booleans and anything that parses as a number becomes one. So `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` hands a JSON number to a string field and fails the whole configuration parse, with an error that does not name the field. Quote such values into non-numeric form, or set them in TOML.
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+`http_sink` calls its equivalent knob `max_payload_size_bytes`. The names differ deliberately: the sink's bounds an outgoing payload, this one bounds an accepted request.
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 405 | A known path with the wrong method | `{"error":"method not allowed"}` |
+| 429 | Bridge full | `{"error":"too many requests"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling; a named-path POST whose route changed hands while the body was still arriving; a POST whose instance left the listener mid-request; or a POST whose instance bridge has no receiver | `{"status":"unavailable"}`, `{"error":"route unavailable"}`, `{"error":"instance is closing"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+The named path splits those two cases on purpose. A path that is not configured answers 404, which is permanent and correct. A configured path whose instance stopped serving it while the body was still arriving answers 503 instead: that caller already passed bearer auth, the path does exist, and only which instance serves it changed.
+
+A 404 there would tell a conventional client the resource is gone, and it would stop retrying, so a republish window would silently drop traffic that succeeds a moment later. The secret path keeps 404 for both cases, because its caller is unauthenticated and separating "wrong id" from "busy" would leak which ids exist.
+
+The named path's 503 covers two conditions and says `route unavailable` for both: the path was withdrawn, or another instance on the same listener took it over. The caller retries either way, and the body deliberately does not say which, since that would describe the listener's topology to a sender that has no use for it.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | TCP peer address. Behind the load balancer this README recommends, that is the proxy, not the sender; forward `X-Forwarded-For` to see the original client |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 202
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only: a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |
+| ------ | --------- |
+| 400 | Empty `auth_secret`; an `auth_secret` supplied with `auth_type: none`; an `expires_at` already in the past; an `hmac_header` that is not a valid HTTP header name; a `reason`, `auth_secret`, `hmac_header` or `hmac_prefix` past its length cap |
+| 401 | Missing or wrong `management_token` |
+| 404 | Unknown endpoint, unknown `instance`, or the API is not configured |
+| 409 | Rotating a static endpoint, an endpoint whose `auth_type` is `none`, or one that has expired; or a generated id collision |
+| 415 | Missing or wrong `Content-Type` on a request that takes a body |
+| 422 | A body that parses as JSON but carries an unknown field or a wrong type |
+| 500 | The route table could not be rebuilt |
+| 503 | The owning instance closed while the request was in flight |
+| 507 | The registry is at `MAX_ENDPOINTS` with no reclaimable tombstone |
+
+Revocation writes a tombstone rather than deleting the entry. The tombstone persists, so a restart against a stale TOML file cannot resurrect an endpoint someone revoked. That rests on `open()` failing when the state file cannot be decoded, rather than falling back to the TOML: the connector reports the decode failure as `last_error` and serves nothing, instead of quietly putting revoked endpoints back on the wire.
+
+The 202 means the endpoint stopped serving *now*, in memory, and that the tombstone has been accepted but not yet persisted. It is deliberately not a 204: the change reaches the runtime only on a later `poll()`, and `submitted` flips before the state leaves the plugin, so no field on this response could honestly claim durability. Watch `GET /admin/endpoints/{id}` for it.
+
+Durability follows the same path as registration below, with one asymmetry worth knowing: losing an unsaved registration fails closed, but losing an unsaved revocation fails **open**, so the endpoint would come back after a restart.
+
+`submitted` on `GET /admin/endpoints/{id}` is not the durability check. It flips when the mutation is handed to the runtime, which happens before the runtime persists it. A save that failed shows up as `last_error` on the connector and re-arms the flush for the next poll, so treat a revocation as final only once the connector is error-free. If it cannot reach Iggy, remove the endpoint from the TOML too.
+
+Dynamic endpoints ride the SDK's `ConnectorState`, which the runtime writes after the next successful send. A management response therefore means "accepted", not "durable": if Iggy is unreachable, the endpoint is live in memory but not yet on disk, and a crash in that window loses it.
+
+`GET /admin/endpoints` reports `submitted` per endpoint. It is named that, and not `persisted`, on purpose: it says the registry was handed to the runtime, not that the write landed.
+
+It is answered per endpoint but derived instance-wide, because that is what the mechanism is. The registry is serialized and handed over whole, so no endpoint in it can be submitted while another is not, and one outstanding flush makes every endpoint unsubmitted until it lands. Since #3855 the runtime acknowledges the batch, and a failed save comes back as a NACK that re-arms the flush for the next poll, which puts the endpoints back to `submitted: false` too.
+
+That errs toward reporting not-yet-durable, which is the safe direction.
+
+## Backpressure
+
+The chain below holds end to end. It did not always: the runtime's forwarding channel is unbounded, so a slow Iggy used to show up as memory growth rather than backpressure, and #3795 proposed bounding it.
+
+What closed the gap instead was #3855. The SDK now keeps one batch in flight and will not call `poll()` again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop directly. The bridge then fills on arrival and the handlers answer 429, which is the coupling that was missing.
+
+That coupling holds only while the runtime answers inside the SDK's batch-result timeout, 30s. Past it the SDK stops waiting, NACKs, and polls again, so the bridge drains and the pressure moves into the runtime's unbounded forwarding channel instead of reaching the sender. Tracked in #3981.
+
+```text
+Iggy slow -> forwarding loop blocks -> batch stays unacknowledged -> poll() stalls
+          -> instance bridge fills -> HTTP 429 + Retry-After: 1
+```
+
+The handler never blocks on a full bridge. Waiting would hold connections open and, once the sender times out, produce a retry storm; a fast 429 tells the sender exactly what to do.
+
+| Traffic | `buffer_capacity` | Rationale |
+| ------- | ----------------- | --------- |
+| Under 100 req/s | 1000 | Small footprint |
+| 100 to 1000 req/s | 10000 (default) | Absorbs roughly ten seconds of burst |
+| Over 1000 req/s | 50000 to 100000 | Sustained bursts; tune against the buffer metrics |
+
+The bridge is bounded by message count, not bytes, so its worst case is `buffer_capacity * max_body_size_bytes`. At the defaults that is about 10 GB. Add the in-flight batch on top: at the moment of a send a batch exists as the staged copy this connector holds for replay, the SDK's serialized copy, and the runtime's decoded copy, so budget up to three times `max_batch_size * max_body_size_bytes` above the bridge. Size all of them together.

Review Comment:
   Two corrections here. The copy count is one short: `postcard::to_allocvec` at `core/connectors/sdk/src/source.rs:306` shadows rather than moves, so the polled `ProducedMessages` lives to the end of the `select!` arm at `:414`, past the callback and past the result await. Peak is four concurrent copies (staged, polled, serialized, runtime-decoded), not three. The earlier round's "three (staged, sdk, runtime decoded)" missed the same one.
   
   Second, the paragraph carries no term for concurrent in-flight request bodies. Both POST handlers buffer up to `max_body_size_bytes` before any bridge check, nothing caps connections, and at a 64 MiB cap that term dominates the bridge and the batches together. Add it, and point at the reverse-proxy note at `:348` for what bounds it.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only

Review Comment:
   `last_poll_was_state_only` is stored from `state.is_some()`, so the `take_dirty_state` declined path stores `false` and the next poll is flush-first again. The guard described at `lib.rs:922-931` therefore holds only when a flush succeeds.
   
   Declined is reachable with no panic and no poisoning: `try_lock` at `lib.rs:461` loses to an ordinary `try_mutate_registry`, which holds `registry_writer` across `EndpointRegistry::clone` plus `validate` (`lib.rs:306-316`). The decline arm re-posts the permit, the biased flush-first arm consumes it at once, `recv()` is never polled, and it repeats. Result is empty FFI round trips plus queued traffic going undrained while control-plane writers keep the lock hot.
   
   Flip when the flush arm wins rather than when it produced state.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let now_seconds = unix_now_seconds();
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // The same rule registration applies, asked here and only warned
+            // about. `restore` failing is a hard `open()` failure, so refusing
+            // would take a whole instance down over one stored value an
+            // operator cannot edit without the state file.
+            //
+            // Asked rather than re-derived, because the two hand-written checks
+            // that used to live here had already drifted from it: they covered
+            // the ceilings and a malformed `hmac_header`, and silently skipped
+            // an endpoint advertising auth with no usable secret. That one
+            // restores active, reads active on the admin API, and rejects every
+            // request forever, which is fail-closed and completely silent.
+            //
+            // `Existing`, so a stored `expires_at` that has merely passed is not
+            // reported as a fault: the endpoint answers 404 on its own path and
+            // that is the documented behaviour.
+            //
+            // Skipped for an endpoint whose expiry has already passed. Its
+            // secret is cleared below, so on the next restart this rule would
+            // report `MissingSecret` and blame the credential for a refusal
+            // that expiry already explains.
+            if !revoked
+                && !endpoint.is_expired(now_seconds)
+                && let Err(reason) = admit_endpoint(
+                    endpoint.auth_type,
+                    &endpoint.auth_secret,
+                    &endpoint.hmac_header,
+                    &endpoint.hmac_prefix,
+                    endpoint.expires_at,
+                    Admission::Existing,
+                )
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id}: {reason}; it is served but every request to it will be refused until it is re-registered",
+                    endpoint_id.log_prefix()
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    // The map was seeded from TOML, so Occupied means TOML
+                    // still declares this id: the tombstone is static whatever
+                    // the state file says. Taking the persisted `origin`
+                    // verbatim let a `Dynamic` tombstone be the entry that
+                    // outranks a live TOML block, and `reclaimable_tombstones`
+                    // evicts exactly the dynamic ones, so the next restart
+                    // served that endpoint and its secret again. Reclamation is
+                    // only safe because a static tombstone is never eligible.
+                    endpoint.origin = EndpointOrigin::Static;
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    // A static entry reaches this arm only when TOML no longer
+                    // declares it. Restoring an active one resurrects an
+                    // endpoint the operator decommissioned by deleting it, and
+                    // `rotate_secret` then refuses it as static and points at a
+                    // TOML entry that is gone, so there is no way back. Its
+                    // tombstone still has to survive: re-adding the id to TOML
+                    // later must not undo a revocation.
+                    if !revoked && endpoint.origin == EndpointOrigin::Static {
+                        dropped_static += 1;
+                        continue;
+                    }
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        // Same reasoning as `revoke()`: the handler answers 404 on an expired
+        // endpoint before `authorize()` runs, so its stored secret is already
+        // dead weight, and nothing compacts the registry. Keeping it wrote a
+        // credential the operator can no longer use back to disk on every later
+        // flush, indefinitely, which is exactly what `revoke()` clears the
+        // secret to avoid.
+        //
+        // The endpoint keeps its slot and stays `Active`. Reclaiming it would
+        // make endpoints disappear on a clock condition rather than an operator
+        // action.
+        //
+        // Restore only, deliberately. An endpoint that expires while the
+        // instance is running keeps its stored secret until the next restart,
+        // because clearing it then would need a clock-driven sweep mutating the
+        // registry from `poll()`. `revoke` is what clears it immediately.
+        let mut expired_secrets = 0;
+        for endpoint in endpoints.values_mut() {
+            if endpoint.is_active()
+                && endpoint.is_expired(now_seconds)
+                && endpoint.auth_secret.is_some()
+            {
+                endpoint.auth_secret = None;

Review Comment:
   Clearing the secret here never arms a flush. `registry_dirty` is constructed `false` (`lib.rs:772`) and only `try_mutate_registry` and `rearm_state_flush` set it, so the credential stays in the state file until some unrelated mutation flushes, and never at all on a static-only instance.
   
   `README.md:138` says the stored secret "is dropped on the next restart", and `:142` explains the clear as avoiding writing it back on every later flush. An operator reading that skips the revoke and leaves a leaked secret on disk in clear.
   
   Reword both lines rather than arming the flag here. Arming alone posts no permit, so a quiet gateway still never flushes, and arming plus notifying breaks the "static-only instance writes no state file" contract at `lib.rs:440-441` and `README.md:338`.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)
+            && !self.instances.is_empty()
+            && self
+                .instances
+                .iter()
+                .all(|instance| instance.poll_is_live(now_seconds))
+    }
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        // Without these, a mistyped path got axum's empty-bodied 404 and a
+        // wrong method an undocumented 405, while every other response on this
+        // listener carries `{"error": ...}`. A sender parsing that field broke
+        // on exactly the two responses a misconfiguration produces.
+        //
+        // The admin listener deliberately keeps axum's bare fallback: an
+        // unconfigured management API is not mounted at all there, and
+        // answering with this crate's error shape would make "no token
+        // configured" look like a route that exists and refused.
+        .fallback(|| async { error_response(StatusCode::NOT_FOUND, "not found") })
+        .method_not_allowed_fallback(|| async {
+            error_response(StatusCode::METHOD_NOT_ALLOWED, "method not allowed")
+        })
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+/// A request that resolved to no instance is still metered, under [`UNROUTED`],
+/// which is where a scan for live endpoint ids shows up.
+fn instance_label(instance: Option<&Arc<SharedState>>) -> &str {
+    instance.map_or(UNROUTED, |instance| instance.instance_name.as_str())
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) = named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// The instance the request resolved to, for the caller to label metrics with.
+/// Returning the `Arc` the lookup already produced rather than a copy of its
+/// name keeps the label allocation-free on the request path; `None` is a
+/// request that resolved to no instance, counted under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands them over owned, so nothing is cloned to survive the
+    // body being taken.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+        };
+        Arc::clone(instance)
+    };
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            Some(instance),
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (Some(instance), oversized_body_response(&error)),
+    };
+    // Resolved again for the same reason the secret path does it: the answer
+    // above is stale by however long the client took to send its body, and
+    // nothing bounds that. An instance that left in the meantime still owns a
+    // bridge whose receiver lives in `HttpSource`, so `try_send` would succeed
+    // and answer 200 for a message no `poll()` will ever drain. `leave()` reads
+    // `sender.len()` for `dropped_on_close` before that message exists, so the
+    // loss would not even be counted. `ptr_eq` also covers the swap: one
+    // instance leaves and another joins claiming the same topic path, and this
+    // request was never authorized against that one.
+    let published = state.published();
+    let serving = match published.routes.lookup_named_path(topic_path) {
+        Some(serving) if Arc::ptr_eq(serving, &instance) => serving,
+        // 503, not the 404 the first lookup answers. This caller already passed
+        // bearer auth and the path it asked for does exist; what changed is
+        // which instance serves it, mid-request. A 404 tells a sender the
+        // resource is gone and conventional clients stop retrying, so a
+        // republish window silently drops traffic that would have succeeded a
+        // moment later. `management.rs` already answers 503 for this same
+        // condition. The secret path keeps its 404 deliberately: that caller is
+        // unauthenticated, and distinguishing "wrong id" from "busy" there
+        // would confirm which endpoint ids exist.
+        //
+        // "route unavailable" rather than the "instance is closing" the admin
+        // API uses, because this arm covers two conditions and only one of them
+        // is a closure: the lookup can return nothing because the path was
+        // withdrawn, or it can return a different instance that has taken the
+        // path over. Naming a closure would be wrong for the handover, and the
+        // caller's action is the same either way. It also says no more about
+        // the listener's topology than a retry needs.
+        _ => {
+            return (
+                Some(instance),
+                error_response(StatusCode::SERVICE_UNAVAILABLE, "route unavailable"),
+            );
+        }
+    };
+    let response = enqueue(serving, &request_headers, remote_addr, body, &state.metrics);
+    (Some(instance), response)
+}
+
+async fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands the headers over owned; taking them as an extractor
+    // cloned the whole map on every request.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    // Scoped, so the published view is not pinned across the body read below.
+    // The read is paced by the client, so holding it would keep every route
+    // table and instance set reachable for as long as a caller cares to
+    // trickle, and would decide the outcome from a view taken before it began.
+    let instance = {
+        let published = state.published();
+        match published
+            .routes
+            .lookup_secret_path(endpoint_id, unix_now_seconds())
+        {
+            RouteLookup::Active(entry) => Arc::clone(&entry.instance),
+            // Both answer as if the endpoint never existed, so a leaked URL
+            // cannot be used to confirm it was once live: a 410 for the expired
+            // case would be returned before any credential is checked and would
+            // say exactly that. The metric still names the owning instance, so
+            // only a genuinely unknown path is `unrouted`.
+            RouteLookup::Revoked(entry) | RouteLookup::Expired(entry) => {
+                return (
+                    Some(Arc::clone(&entry.instance)),
+                    error_response(StatusCode::NOT_FOUND, "not found"),
+                );
+            }
+            RouteLookup::Unknown => {
+                return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+            }
+        }
+    };
+    // Only now, once the id resolved to something that is actually serving.
+    // An unknown or revoked id used to cost a full body read before its 404,
+    // which is free amplification on the public listener. HMAC still needs the
+    // body, so the read cannot move any earlier than this.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,

Review Comment:
   The body is read here and HMAC-verified at `:782-787` before anything checks the bridge; the `is_full` gate sits in `enqueue` at `server.rs:923`. So a full bridge answers 429 only after buffering up to `max_body_size_bytes` and hashing it, and the `Retry-After: 1` behaviour at `README.md:288-291` has senders re-upload and re-verify every body it sheds.
   
   The earlier round asked for this check ahead of the header map and the body copy. Landing it inside `enqueue` saved those two but not the read.
   
   A relaxed `instance.sender.is_full()` before `to_bytes`, here and at `:674`, covers it. Additive only: the second resolve, `authorize`, `try_send` and the post-send `has_departed` check all stay the real gates.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only
+                .store(state.is_some(), Ordering::Release);
+            state
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        self.last_batch_carried_state
+            .store(state.is_some(), Ordering::Release);
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free.
+    ///
+    /// A Nack does not mean neither happened. The runtime NACKs a batch it sent
+    /// successfully but whose state it could not persist, and the SDK NACKs on
+    /// its own result timeout while that send may still have landed. Holding
+    /// the copy and replaying it is therefore at-least-once by construction:
+    /// the alternative, dropping it, would turn every one of those into
+    /// silent loss.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();

Review Comment:
   `clear_state_flush_backoff` runs on every Ack, including a traffic batch, so `state_flush_nacks` is zeroed by work unrelated to the flush. `state_flush_retry_delay(0)` is `Duration::ZERO`, so the "doubles to an eight second ceiling" documented at `lib.rs:1032-1038` never engages while traffic is flowing.
   
   This bites on the default File backend, not only the HTTP one: `StateStorage::is_latched` returns `false` unconditionally for `File` (`runtime/src/state.rs:70-75`), so a persistent save failure (read-only mount, ENOSPC, EPERM on the state dir) NACKs the state-only batch while traffic batches Ack. `consecutive_nacks` then alternates, so the SDK never stops the source: one failed write per poll indefinitely, which on the HTTP backend is a remote write per poll.
   
   Reset the counter only when `last_batch_carried_state` is true.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,

Review Comment:
   A typo in this key deserializes to `None`, and the named-path handler skips its whole auth block, so `POST /topics/{topic_path}` serves unauthenticated. `deny_unknown_fields` is correctly not an option, since the runtime's env overrides arrive as flat keys, so the typo stays silent by design.
   
   The only mitigation is the `warn!` at `lib.rs:353-356`, which does reach the operator's log because the callback is installed before `factory`. Nothing documents it: not the Options row at `README.md:120`, not the env-override section at `:144-146`, not Operational notes.
   
   Worth an Options row saying unknown `plugin_config` keys are ignored, plus an operational note to grep the open log for "with NO authentication".



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)
+            && !self.instances.is_empty()
+            && self
+                .instances
+                .iter()
+                .all(|instance| instance.poll_is_live(now_seconds))
+    }
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        // Without these, a mistyped path got axum's empty-bodied 404 and a
+        // wrong method an undocumented 405, while every other response on this
+        // listener carries `{"error": ...}`. A sender parsing that field broke
+        // on exactly the two responses a misconfiguration produces.
+        //
+        // The admin listener deliberately keeps axum's bare fallback: an
+        // unconfigured management API is not mounted at all there, and
+        // answering with this crate's error shape would make "no token
+        // configured" look like a route that exists and refused.
+        .fallback(|| async { error_response(StatusCode::NOT_FOUND, "not found") })
+        .method_not_allowed_fallback(|| async {
+            error_response(StatusCode::METHOD_NOT_ALLOWED, "method not allowed")
+        })
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))

Review Comment:
   This couples control-plane request size to the webhook cap. A max-legal registration body is about 4.7 KiB (`auth_secret` 4096 + `hmac_header` 256 + `hmac_prefix` 64 + `instance` up to 255 + envelope), so any `max_body_size_bytes` below that makes registration and rotation impossible, and `validate`'s floor is 1 (`lib.rs:609`). `RotateRequest` carries only `auth_secret`, so what this blocks is incident-time secret rotation, answering `{"error":"invalid request body"}` naming neither field nor cause.
   
   It also overshoots the ask, which was that the admin listener not silently use axum's 2 MiB default. Explicit field caps landed later at `auth.rs:62-64` as the tool for bounding these values, and `ensure_compatible` refuses a join disagreeing on `max_body_size_bytes`, so it cannot be raised for one instance.
   
   Give the admin limit its own const sized off the field caps.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3956443337


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2189 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::admit_endpoint;
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies. Written out here
+            // once, these checks drifted: config admitted an `auth_type: none`
+            // carrying a secret, which then rode into the state file in clear
+            // where nothing reads it, and an `expires_at` already past, which
+            // 404s forever with only the serving count as a hint.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(

Review Comment:
   critical: one static endpoint whose `expires_at` has passed fails the whole instance, so unedited TOML that starts today dies on tomorrow's unattended restart and takes every other endpoint with it. README line 138 promises a 404 instead. scope the check to the endpoint like `restore` does.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,344 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |

Review Comment:
   warning: `buffer_capacity`, `max_batch_size` and `max_body_size_bytes` each have a hard ceiling that fails `open()`, and none of the three is documented. add a max column.



##########
core/integration/tests/connectors/http/http_source.rs:
##########
@@ -0,0 +1,556 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use super::{POLL_ATTEMPTS, POLL_INTERVAL_MS};
+use crate::connectors::fixtures::{
+    GITHUB_ENDPOINT_ID, GITHUB_HMAC_HEADER, GITHUB_INSTANCE, HttpSourceFixture, MANAGEMENT_TOKEN,
+    PARTNER_BEARER_TOKEN, PARTNER_ENDPOINT_ID, PARTNER_INSTANCE,
+};
+use iggy::prelude::IggyClient;
+use iggy_common::MessageClient;
+use iggy_common::{Consumer, Identifier, PollingStrategy};
+use iggy_connector_sdk::api::{ConnectorStatus, SourceInfoResponse};
+use integration::harness::seeds;
+use integration::iggy_harness;
+use reqwest::{Client, StatusCode};
+use serde_json::{Value, json};
+use std::time::Duration;
+use tokio::time::sleep;
+
+const API_KEY: &str = "test-api-key";
+const RESTORED_TOKEN: &str = "token-that-must-survive-a-restart";
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn webhook_post_produces_message_to_iggy(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push","repository":"apache/iggy"}"#;
+    let response = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .header("X-GitHub-Delivery", "72d3162e-cc78-11e3-81ab-4c9367dc0958")
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST the webhook");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_1", 1).await;
+    assert_eq!(
+        String::from_utf8_lossy(&messages[0].0),
+        body,
+        "the raw request body must reach Iggy byte for byte"
+    );
+    let headers = messages[0]
+        .1
+        .as_ref()
+        .expect("HTTP metadata forwarding is enabled");
+    assert_eq!(
+        header_value(headers, "iggy_source_instance").as_deref(),
+        Some(GITHUB_INSTANCE)
+    );
+    assert_eq!(
+        header_value(headers, "X-GitHub-Delivery").as_deref(),
+        Some("72d3162e-cc78-11e3-81ab-4c9367dc0958"),
+        "the delivery id is the consumer's dedup key and must survive the FFI hop"
+    );
+}
+
+/// The secret path is covered above; nothing exercised the named one, which is
+/// the route an operator gets by setting `topic_path` and the one a typo in
+/// `auth_bearer_token` would leave open.
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn named_path_post_produces_message_to_iggy(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"deployment","environment":"staging"}"#;
+    let response = http
+        .post(fixture.named_url(seeds::names::TOPIC))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the named path");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_named", 1).await;
+    assert_eq!(
+        String::from_utf8_lossy(&messages[0].0),
+        body,
+        "the named path must deliver the raw body byte for byte, same as the secret path"
+    );
+    let headers = messages[0]
+        .1
+        .as_ref()
+        .expect("HTTP metadata forwarding is enabled");
+    assert_eq!(
+        header_value(headers, "iggy_source_instance").as_deref(),
+        Some(GITHUB_INSTANCE),
+        "and must attribute the message to the instance that owns the topic_path"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn two_instances_share_one_listener(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let github_body = r#"{"from":"github"}"#;
+    let github = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(github_body.as_bytes()),
+        )
+        .body(github_body)
+        .send()
+        .await
+        .expect("Failed to POST to the GitHub endpoint");
+    let partner_body = r#"{"from":"partner"}"#;
+    let partner = http
+        .post(fixture.webhook_url(PARTNER_ENDPOINT_ID))
+        .header("Authorization", format!("Bearer {PARTNER_BEARER_TOKEN}"))
+        .body(partner_body)
+        .send()
+        .await
+        .expect("Failed to POST to the partner endpoint");
+
+    assert_eq!(github.status(), StatusCode::OK);
+    assert_eq!(
+        partner.status(),
+        StatusCode::OK,
+        "the second instance must be reachable on the port the first one bound"
+    );
+
+    let first = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_2a", 1).await;
+    let second = poll_payloads(&client, seeds::names::TOPIC_2, "http_source_cg_2b", 1).await;
+    assert_eq!(String::from_utf8_lossy(&first[0].0), github_body);
+    assert_eq!(
+        String::from_utf8_lossy(&second[0].0),
+        partner_body,
+        "one listener, but each instance produces to its own topic"
+    );
+    assert_eq!(
+        header_value(
+            second[0].1.as_ref().expect("metadata is on by default"),
+            "iggy_source_instance"
+        )
+        .as_deref(),
+        Some(PARTNER_INSTANCE)
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn management_registered_endpoint_accepts_until_revoked(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let endpoint_id = register_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    let body = r#"{"event":"dynamic"}"#;
+    let accepted = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the registered endpoint");
+    assert_eq!(
+        accepted.status(),
+        StatusCode::OK,
+        "an endpoint registered through the API must serve without a restart"
+    );
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_3", 1).await;
+    assert_eq!(String::from_utf8_lossy(&messages[0].0), body);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{endpoint_id}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the endpoint");
+    assert_eq!(revoked.status(), StatusCode::ACCEPTED);
+
+    let after = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the revoked endpoint");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "a revocation must take effect immediately, and must not leak that the URL once worked"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn dynamic_endpoint_survives_connector_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    // Registered with a secret so the restart proves the credential survives
+    // the state round trip, not merely the endpoint id.
+    let endpoint_id = register_secured_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    // The registry only reaches the runtime once a poll carrying it has been
+    // sent, so wait for the connector to report it submitted before pulling
+    // the rug out from under it.
+    wait_for_submitted(&http, &fixture, &endpoint_id).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(
+        restarted.status().is_success(),
+        "Restart request failed: {}",
+        restarted.status()
+    );
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let authorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .header("Authorization", format!("Bearer {RESTORED_TOKEN}"))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    let unauthorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+
+    assert_eq!(
+        authorized.status(),
+        StatusCode::OK,
+        "an endpoint that only ever existed in ConnectorState must come back with the connector"
+    );
+    assert_eq!(
+        unauthorized.status(),
+        StatusCode::UNAUTHORIZED,
+        "and its secret must come back with it, not be dropped to an open endpoint"
+    );
+}
+
+/// The README's strongest security claim: a revoked endpoint must not be
+/// resurrected by a restart that re-reads the TOML still declaring it.
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn revoked_static_endpoint_stays_revoked_across_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push"}"#;
+    let before = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST before revocation");
+    assert_eq!(before.status(), StatusCode::OK);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{GITHUB_ENDPOINT_ID}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the static endpoint");
+    assert_eq!(revoked.status(), StatusCode::ACCEPTED);
+    wait_for_submitted(&http, &fixture, GITHUB_ENDPOINT_ID).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(restarted.status().is_success());
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let after = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "the tombstone must outlive the restart even though http_github.toml still declares this endpoint"
+    );
+}
+
+/// Keep-alive is off on purpose. The gateway shuts down gracefully, so an idle
+/// pooled socket holds the listener open until its shutdown timeout expires,
+/// stalling harness teardown for seconds per test.
+fn webhook_client() -> Client {
+    Client::builder()
+        .pool_max_idle_per_host(0)
+        .build()
+        .expect("Failed to build the webhook client")
+}
+
+/// The listener binds during the connector's `open()`, which happens after the
+/// runtime's own HTTP API is already answering.
+///
+/// Waits for *both* instances by name. The public `/health` answers as soon as
+/// one instance is serving, and the two open independently, so returning on the
+/// first left every later request racing the second: a post to
+/// `PARTNER_ENDPOINT_ID` would 404, and a registration against `GITHUB_INSTANCE`
+/// would come back "unknown instance", depending on which won.
+async fn wait_for_gateway(http: &Client, fixture: &HttpSourceFixture) {
+    for _ in 0..POLL_ATTEMPTS {
+        if let Ok(response) = http
+            .get(format!("{}/admin/health", fixture.admin_url()))
+            .send()
+            .await
+            && response.status() == StatusCode::OK
+            && let Ok(health) = response.json::<Value>().await
+        {
+            let joined: Vec<&str> = health["instances"]
+                .as_array()
+                .map(|instances| {
+                    instances
+                        .iter()
+                        .filter_map(|instance| instance["instance"].as_str())
+                        .collect()
+                })
+                .unwrap_or_default();
+            if joined.contains(&GITHUB_INSTANCE) && joined.contains(&PARTNER_INSTANCE) {
+                return;
+            }
+        }
+        sleep(Duration::from_millis(POLL_INTERVAL_MS)).await;
+    }
+    panic!("Both webhook gateway instances did not join in time");
+}
+
+/// Registers a bearer-guarded endpoint, so a test can prove the secret and not
+/// just the id survives whatever it does next.
+async fn register_secured_endpoint(
+    http: &Client,
+    fixture: &HttpSourceFixture,
+    instance: &str,
+) -> String {
+    let response = http
+        .post(format!("{}/admin/endpoints", fixture.admin_url()))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({
+            "instance": instance,
+            "auth_type": "bearer",
+            "auth_secret": RESTORED_TOKEN,
+        }))
+        .send()
+        .await
+        .expect("Failed to register a secured endpoint");
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let body: Value = response
+        .json()
+        .await
+        .expect("Registration must return JSON");
+    body["endpoint_id"]
+        .as_str()
+        .expect("Registration must return an endpoint id")
+        .to_string()
+}
+
+async fn register_endpoint(http: &Client, fixture: &HttpSourceFixture, instance: &str) -> String {
+    let response = http
+        .post(format!("{}/admin/endpoints", fixture.admin_url()))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"instance": instance}))
+        .send()
+        .await
+        .expect("Failed to register an endpoint");
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let body: Value = response
+        .json()
+        .await
+        .expect("Registration must return JSON");
+    body["endpoint_id"]
+        .as_str()
+        .expect("Registration must return an endpoint id")
+        .to_string()
+}
+
+async fn wait_for_submitted(http: &Client, fixture: &HttpSourceFixture, endpoint_id: &str) {

Review Comment:
   warning: `submitted` means the registry left the plugin, not that the file landed, so both callers can restart before anything is on disk and go red at random. wait on the state file, or retry the assertion after the restart.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2189 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::admit_endpoint;
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies. Written out here
+            // once, these checks drifted: config admitted an `auth_type: none`
+            // carrying a secret, which then rode into the state file in clear
+            // where nothing reads it, and an `expires_at` already past, which
+            // 404s forever with only the serving count as a hint.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                unix_now_seconds(),
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only
+                .store(state.is_some(), Ordering::Release);
+            state
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        self.last_batch_carried_state
+            .store(state.is_some(), Ordering::Release);
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free.
+    ///
+    /// A Nack does not mean neither happened. The runtime NACKs a batch it sent
+    /// successfully but whose state it could not persist, and the SDK NACKs on
+    /// its own result timeout while that send may still have landed. Holding
+    /// the copy and replaying it is therefore at-least-once by construction:
+    /// the alternative, dropping it, would turn every one of those into
+    /// silent loss.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();
+                self.shared.clear_state_flush_backoff();
+                Ok(())
+            }
+            source::SourceBatchResult::Nack => self.on_nack(),
+        }
+    }
+
+    async fn close(&mut self) -> Result<(), Error> {
+        // Counted before `leave`, which is what folds it into
+        // `http_source_dropped_on_close_total` alongside the bridge. Leaving it
+        // to a log line under-reported shutdown loss by up to `max_batch_size`.
+        let staged_dropped = match self.lock_staged().take() {
+            Some(staged) => {
+                warn!(
+                    "Dropping {} unacknowledged messages for {CONNECTOR_NAME} connector ID: {}",
+                    staged.messages.len(),
+                    self.shared.id
+                );
+                staged.messages.len() as u64
+            }
+            None => 0,
+        };
+        // A mutation made after the last poll never reached the runtime, and
+        // there is no poll left to carry it. The endpoint is live again after
+        // the restart while the admin API reported the change applied, so this
+        // is the only record that it did not stick. `close()` has no way to
+        // flush it: state reaches the runtime only as the return value of
+        // `poll()`.
+        if self.shared.has_pending_state() {
+            warn!(
+                "Closing {CONNECTOR_NAME} connector ID: {} with an unflushed registry: {} change(s) not submitted, so a change made since the last poll will not survive the restart",
+                self.shared.id,
+                self.shared.pending_change_count()
+            );
+        }
+        // The SDK stops the poll task before calling this, so anything still
+        // in the bridge is already unreachable. Deregistering first is what
+        // stops new requests from being accepted into a queue nobody drains.
+        server::leave(&self.shared, staged_dropped).await;
+        info!("Closed {CONNECTOR_NAME} connector ID: {}", self.shared.id);
+        Ok(())
+    }
+}
+
+/// Backoff before re-posting a state flush the runtime refused.
+///
+/// The first retry is immediate, so an isolated refusal costs nothing. Past
+/// that it doubles to an eight second ceiling, which is inside the SDK's
+/// result timeout, so a store that recovers is picked up promptly. A store
+/// that stays latched still ends in the SDK stopping the source; that is
+/// #3941's subject, not something this connector can fix from the inside.
+fn state_flush_retry_delay(attempt: u32) -> Duration {
+    match attempt {
+        0 => Duration::ZERO,
+        n => Duration::from_millis(250u64 << (n - 1).min(5)),
+    }
+}
+
+fn default_admin_listen_addr() -> String {
+    DEFAULT_ADMIN_LISTEN_ADDR.to_string()
+}
+
+fn default_max_body_size_bytes() -> usize {
+    DEFAULT_MAX_BODY_SIZE_BYTES
+}
+
+fn default_buffer_capacity() -> usize {
+    DEFAULT_BUFFER_CAPACITY
+}
+
+fn default_max_batch_size() -> usize {
+    DEFAULT_MAX_BATCH_SIZE
+}
+
+fn default_hmac_header() -> String {
+    DEFAULT_HMAC_HEADER.to_string()
+}
+
+fn default_hmac_prefix() -> String {
+    DEFAULT_HMAC_PREFIX.to_string()
+}
+
+fn default_true() -> bool {
+    true
+}
+
+/// Fixtures shared by the routing and state test modules.
+#[cfg(test)]
+pub(crate) mod test_support {
+    use super::*;
+
+    pub const ENDPOINT_ONE: &str = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d";
+    pub const ENDPOINT_TWO: &str = "b4092d3fa1c85e6b7d0f2a1c3e4b5d6a";
+
+    pub fn endpoint_id(raw_id: &str) -> EndpointId {
+        raw_id.parse().expect("test endpoint id must be valid")
+    }
+
+    pub fn static_endpoint(raw_id: &str) -> StaticEndpointConfig {
+        StaticEndpointConfig {
+            endpoint_id: endpoint_id(raw_id),
+            auth_type: EndpointAuthType::HmacSha256,
+            auth_secret: Some(SecretString::from("whsec_static")),
+            hmac_header: DEFAULT_HMAC_HEADER.to_string(),
+            hmac_prefix: DEFAULT_HMAC_PREFIX.to_string(),
+            expires_at: None,
+        }
+    }
+
+    pub fn config(topic_path: Option<&str>, endpoint_ids: &[&str]) -> HttpSourceConfig {
+        HttpSourceConfig {
+            listen_addr: "127.0.0.1:9090".to_string(),
+            admin_listen_addr: DEFAULT_ADMIN_LISTEN_ADDR.to_string(),
+            max_body_size_bytes: DEFAULT_MAX_BODY_SIZE_BYTES,
+            buffer_capacity: DEFAULT_BUFFER_CAPACITY,
+            max_batch_size: DEFAULT_MAX_BATCH_SIZE,
+            topic_path: topic_path.map(str::to_string),
+            instance_name: None,
+            auth_bearer_token: None,
+            management_token: None,
+            include_http_metadata: true,
+            forward_headers: Vec::new(),
+            endpoints: endpoint_ids
+                .iter()
+                .map(|raw_id| static_endpoint(raw_id))
+                .collect(),
+        }
+    }
+
+    /// Reserves an ephemeral port and hands it back. Every test that binds
+    /// needs its own, because the listener registry is process-global and the
+    /// test binary runs its cases in parallel.
+    pub fn free_port() -> u16 {
+        std::net::TcpListener::bind("127.0.0.1:0")
+            .expect("the loopback interface must offer a port")
+            .local_addr()
+            .expect("a bound listener has an address")
+            .port()
+    }
+
+    /// No connection pooling: an idle keep-alive socket would hold graceful
+    /// shutdown open until the timeout and slow every teardown to a crawl.
+    pub fn client() -> reqwest::Client {
+        reqwest::Client::builder()
+            .pool_max_idle_per_host(0)
+            .build()
+            .expect("the test client must build")
+    }
+
+    /// Builds one instance's shared state through the real constructor. The
+    /// source itself is dropped, taking the bridge receiver with it: routing
+    /// and state tests resolve and mutate, they never send.
+    pub fn instance(id: u32, topic_path: Option<&str>, endpoint_ids: &[&str]) -> Arc<SharedState> {
+        let source = HttpSource::new(id, config(topic_path, endpoint_ids), None);
+        Arc::clone(&source.shared)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::{ENDPOINT_ONE, ENDPOINT_TWO};
+    use iggy_connector_sdk::source::SourceBatchResult;
+
+    fn minimal_config_json() -> &'static str {
+        r#"{"listen_addr": "0.0.0.0:9090"}"#
+    }
+
+    fn parse(config_json: &str) -> HttpSourceConfig {
+        serde_json::from_str(config_json).expect("config must deserialize")
+    }
+
+    #[test]
+    fn given_minimal_config_when_deserialized_should_apply_defaults() {
+        let config = parse(minimal_config_json());
+        assert_eq!(config.admin_listen_addr, DEFAULT_ADMIN_LISTEN_ADDR);
+        assert_eq!(config.max_body_size_bytes, DEFAULT_MAX_BODY_SIZE_BYTES);
+        assert_eq!(config.buffer_capacity, DEFAULT_BUFFER_CAPACITY);
+        assert_eq!(config.max_batch_size, DEFAULT_MAX_BATCH_SIZE);
+        assert!(config.include_http_metadata);
+        assert!(config.topic_path.is_none());
+        assert!(config.auth_bearer_token.is_none());
+        assert!(config.management_token.is_none());
+        assert!(config.forward_headers.is_empty());
+        assert!(config.endpoints.is_empty());
+    }
+
+    #[test]
+    fn given_minimal_config_when_validated_should_accept() {
+        assert!(parse(minimal_config_json()).validate().is_ok());
+    }
+
+    #[test]
+    fn given_unparsable_listen_addr_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "not-an-address"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("listen_addr")
+        ));
+    }
+
+    #[test]
+    fn given_zero_buffer_capacity_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "buffer_capacity": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("buffer_capacity")
+        ));
+    }
+
+    #[test]
+    fn given_oversized_sizing_values_when_validated_should_reject() {
+        for (field, json) in [
+            (
+                "buffer_capacity",
+                r#"{"listen_addr": "0.0.0.0:9090", "buffer_capacity": 1000001}"#,
+            ),
+            (
+                "max_batch_size",
+                r#"{"listen_addr": "0.0.0.0:9090", "max_batch_size": 100001}"#,
+            ),
+            (
+                "max_body_size_bytes",
+                r#"{"listen_addr": "0.0.0.0:9090", "max_body_size_bytes": 67108865}"#,
+            ),
+        ] {
+            assert!(
+                matches!(
+                    parse(json).validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains(field)
+                ),
+                "{field} had a floor and no ceiling"
+            );
+        }
+    }
+
+    #[test]
+    fn given_unbuildable_buffer_capacity_when_constructed_should_clamp_not_panic() {
+        let mut config = test_support::config(None, &[]);
+        config.buffer_capacity = usize::MAX;
+
+        // `new` builds the crossfire ring, and crossfire asserts on a capacity
+        // this large. That panic would unwind out of `iggy_source_open`, which
+        // is `extern "C"` with no `catch_unwind`, aborting the whole connectors
+        // process. The SDK builds the source before it calls `open`, so
+        // `validate` is not what stands between a typo and that abort.
+        let source = HttpSource::new(1, config, None);
+
+        assert!(
+            source.shared.sender.try_send(queued("one")).is_ok(),
+            "the clamped ring must still be usable"
+        );
+        assert!(
+            matches!(
+                source.shared.config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("buffer_capacity")
+            ),
+            "and open() must still report the misconfiguration rather than serve it"
+        );
+    }
+
+    #[test]
+    fn given_reserved_instance_name_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "instance_name": "unrouted"}"#);
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("reserved")
+            ),
+            "requests matching no route are metered under this name, and that series is the endpoint-id scan signal"
+        );
+    }
+
+    #[test]
+    fn given_config_endpoints_the_api_would_refuse_when_validated_should_refuse_them_too() {
+        // Both were admitted from TOML and refused by the management API, which
+        // is the drift the shared rule exists to stop. The unused secret rides
+        // into the state file in clear where nothing ever reads it; the past
+        // expiry 404s forever with only the serving count as a hint.
+        for (reason, json) in [
+            (
+                "takes no auth_secret",
+                r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                    {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none", "auth_secret": "whsec_unused"}
+                ]}"#,
+            ),
+            (
+                "already past",
+                r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                    {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none", "expires_at": 1}
+                ]}"#,
+            ),
+        ] {
+            let config = parse(json);
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains(reason)
+                ),
+                "config must refuse what the management API refuses: {reason}"
+            );
+        }
+    }
+
+    #[test]
+    fn given_duplicate_endpoint_id_when_validated_should_reject() {
+        let config = parse(
+            r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none"},
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none"}
+            ]}"#,
+        );
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("more than once")
+            ),
+            "the registry is a map, so the second block would silently last-win"
+        );
+    }
+
+    #[test]
+    fn given_invalid_hmac_header_when_validated_should_reject() {
+        let config = parse(
+            r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "hmac-sha256",
+                 "auth_secret": "whsec", "hmac_header": "not a header"}
+            ]}"#,
+        );
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("hmac_header")
+            ),
+            "an invalid name makes HeaderMap::get return None, so every signed request 401s forever"
+        );
+    }
+
+    #[test]
+    fn given_topic_path_with_slash_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "topic_path": "a/b"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("topic_path")
+        ));
+    }
+
+    #[test]
+    fn given_endpoint_with_auth_but_no_secret_when_validated_should_reject() {
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256"
+                }]
+            }"#,
+        );
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("auth_secret")
+        ));
+    }
+
+    #[test]
+    fn given_endpoint_config_when_deserialized_should_apply_hmac_defaults() {
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256",
+                    "auth_secret": "whsec_test"
+                }]
+            }"#,
+        );
+        let endpoint = &config.endpoints[0];
+        assert_eq!(endpoint.hmac_header, DEFAULT_HMAC_HEADER);
+        assert_eq!(endpoint.hmac_prefix, DEFAULT_HMAC_PREFIX);
+        assert_eq!(endpoint.auth_type.hmac_algorithm(), Some(hmac::HMAC_SHA256));
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn given_zero_max_batch_size_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "max_batch_size": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("max_batch_size")
+        ));
+    }
+
+    #[test]
+    fn given_zero_max_body_size_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "max_body_size_bytes": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("max_body_size_bytes")
+        ));
+    }
+
+    #[test]
+    fn given_unparsable_admin_addr_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "admin_listen_addr": "nope"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("admin_listen_addr")
+        ));
+    }
+
+    #[test]
+    fn given_empty_instance_name_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "instance_name": ""}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("instance_name")
+        ));
+    }
+
+    #[test]
+    fn given_oversized_instance_name_when_validated_should_reject() {
+        // It becomes a HeaderKey, and Iggy caps those at 255 bytes. Without
+        // this check the identity header would vanish from every message.
+        let long_name = "n".repeat(256);
+        let config = parse(&format!(
+            r#"{{"listen_addr": "0.0.0.0:9090", "instance_name": "{long_name}"}}"#
+        ));
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("instance_name")
+        ));
+    }
+
+    #[test]
+    fn given_invalid_forward_header_when_validated_should_reject() {
+        // `new()` silently filters entries that fail to resolve, on the stated
+        // assumption that validate() rejects them first. That is the test.
+        let config =
+            parse(r#"{"listen_addr": "0.0.0.0:9090", "forward_headers": ["not a header"]}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("forward_headers")
+        ));
+    }
+
+    #[test]
+    fn given_empty_endpoint_secret_when_validated_should_reject() {
+        // An empty key is valid for HMAC, so accepting one would advertise a
+        // second factor that anyone holding the URL can compute.
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256",
+                    "auth_secret": ""
+                }]
+            }"#,
+        );
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("auth_secret")
+        ));
+    }
+
+    #[test]
+    fn given_empty_management_token_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "management_token": ""}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("management_token")
+        ));
+    }
+
+    #[test]
+    fn given_credential_forward_header_when_validated_should_reject() {
+        for header in ["Authorization", "cookie", "PROXY-AUTHORIZATION"] {
+            let config = parse(&format!(
+                r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{header}"]}}"#
+            ));
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains("credential")
+                ),
+                "{header} would be copied onto every message and persisted in the log"
+            );
+        }
+    }
+
+    #[test]
+    fn given_first_refused_flush_when_retried_should_not_delay() {
+        // An isolated refusal must cost nothing: the store may already be
+        // healthy again by the next poll, and delaying every one of them would
+        // hold a revocation back for no reason.
+        assert_eq!(state_flush_retry_delay(0), Duration::ZERO);
+    }
+
+    #[test]
+    fn given_repeated_refusals_when_retried_should_back_off_to_a_ceiling() {
+        // Growth is what stops a latched store burning the SDK's five-NACK
+        // budget in a tight loop; the ceiling is what stops a recovered store
+        // waiting minutes to be noticed.
+        let delays: Vec<Duration> = (1..=10).map(state_flush_retry_delay).collect();
+        for pair in delays.windows(2) {
+            assert!(
+                pair[1] >= pair[0],
+                "backoff must never shrink, got {:?} then {:?}",
+                pair[0],
+                pair[1]
+            );
+        }
+        assert_eq!(delays[0], Duration::from_millis(250));
+        assert_eq!(
+            *delays.last().expect("range is not empty"),
+            Duration::from_secs(8),
+            "the delay must stop growing well inside the SDK's result timeout"
+        );
+    }
+
+    #[test]
+    fn given_reserved_metadata_forward_header_when_validated_should_reject() {
+        // `message_headers` inserts the metadata first and forwarded headers
+        // into the same map, so without this the sender picks the value the
+        // pipeline trusts. Mixed case because HTTP header names are
+        // case-insensitive and the sender chooses the casing.
+        for header in [
+            INSTANCE_HEADER,
+            REMOTE_ADDR_HEADER,
+            RECEIVED_AT_HEADER,
+            "IGGY_HTTP_REMOTE_ADDR",
+        ] {
+            let config = parse(&format!(
+                r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{header}"]}}"#
+            ));
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains("reserved")
+                ),
+                "{header} would let the sender overwrite the gateway's own metadata"
+            );
+        }
+    }
+
+    #[test]
+    fn given_oversized_forward_header_when_validated_should_reject() {
+        // Valid as an HTTP name, too long to become a HeaderKey. Rejected here
+        // rather than dropped later, so the operator learns the header they
+        // asked to forward would never have ridden along.
+        let long_header = "x".repeat(256);
+        let config = parse(&format!(
+            r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{long_header}"]}}"#
+        ));
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("Iggy header key")
+        ));
+    }
+
+    #[test]
+    fn given_auth_types_when_asked_for_an_algorithm_should_map_each_exactly_once() {
+        // A swapped arm would validate SHA-1 signatures with SHA-256 and
+        // reject every request the sender signs correctly.
+        assert_eq!(
+            EndpointAuthType::HmacSha256.hmac_algorithm(),
+            Some(hmac::HMAC_SHA256)
+        );
+        assert_eq!(
+            EndpointAuthType::HmacSha1.hmac_algorithm(),
+            Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY)
+        );
+        assert_eq!(EndpointAuthType::Bearer.hmac_algorithm(), None);
+        assert_eq!(EndpointAuthType::None.hmac_algorithm(), None);
+    }
+
+    #[test]
+    fn given_invalid_endpoint_id_when_deserialized_should_reject() {
+        let result = serde_json::from_str::<HttpSourceConfig>(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{"endpoint_id": "too-short"}]
+            }"#,
+        );
+        assert!(result.is_err(), "invalid endpoint_id must fail at parse");
+    }
+
+    /// The shipped configurations are documentation, and documentation that
+    /// no longer deserializes is worse than none.
+    #[test]
+    fn given_shipped_configs_when_parsed_should_deserialize_and_validate() {
+        for (name, raw) in [
+            ("config.toml", include_str!("../config.toml")),
+            (
+                "example_config/http_source_github.toml",
+                include_str!("../../../runtime/example_config/connectors/http_source_github.toml"),
+            ),
+            (
+                "example_config/http_source_partner.toml",
+                include_str!("../../../runtime/example_config/connectors/http_source_partner.toml"),
+            ),
+        ] {
+            let document: toml::Value =
+                toml::from_str(raw).unwrap_or_else(|error| panic!("{name} must parse: {error}"));
+            let plugin_config = document
+                .get("plugin_config")
+                .unwrap_or_else(|| panic!("{name} must carry a plugin_config table"))
+                .clone();
+            let config: HttpSourceConfig = plugin_config
+                .try_into()
+                .unwrap_or_else(|error| panic!("{name} plugin_config must deserialize: {error}"));
+            config
+                .validate()
+                .unwrap_or_else(|error| panic!("{name} must pass validation: {error}"));
+        }
+    }
+
+    fn queued(payload: &str) -> QueuedMessage {
+        QueuedMessage {
+            id: 0,

Review Comment:
   warning: `queued()` hardcodes `id: 0`, so nothing checks that a replay keeps the same message id, and 0 is the one value the server replaces. give it a real id and assert it in the nack replay test.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2405 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+/// A request that resolved to no instance is still metered, under [`UNROUTED`],
+/// which is where a scan for live endpoint ids shows up.
+fn instance_label(instance: Option<&Arc<SharedState>>) -> &str {
+    instance.map_or(UNROUTED, |instance| instance.instance_name.as_str())
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) = named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// The instance the request resolved to, for the caller to label metrics with.
+/// Returning the `Arc` the lookup already produced rather than a copy of its
+/// name keeps the label allocation-free on the request path; `None` is a
+/// request that resolved to no instance, counted under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands them over owned, so nothing is cloned to survive the
+    // body being taken.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+        };
+        Arc::clone(instance)
+    };
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            Some(instance),
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (Some(instance), oversized_body_response(&error)),
+    };
+    let response = enqueue(

Review Comment:
   critical: the instance is resolved before the body read, so a request landing while it closes gets a 200 for a message nothing will drain, and `leave` already took the drop count. copy the re-lookup and `Arc::ptr_eq` guard from `secret_path_outcome`.



##########
.claude/skills/connector-source/SKILL.md:
##########
@@ -86,7 +107,7 @@ Match `ProducedMessages.schema` to the bytes in `messages[i].payload`:
 ### Concurrency
 
 - Runtime spawns ONE `poll()` task per source. No concurrent `poll()`.
-- Don't spawn your own long-running Tokio tasks - runtime owns lifecycle.
+- Don't spawn your own long-running Tokio tasks: the runtime owns lifecycle. The exception is a source that listens rather than polls, which has to own its listener; `http_source` is the worked example, and it shuts its tasks down in the last `close()` rather than leaving them to outlive the connector.

Review Comment:
   warning: this sanctions a listener task, but pitfall 8 at line 155 still bans side tasks outright. update the pitfall to match.



##########
.claude/skills/connector-testing/SKILL.md:
##########
@@ -54,6 +54,33 @@ fn given_payload_json_should_serialize_correctly() { ... }
 
 You may **omit one part** when the test is small (`given_X_should_Y` instead of full `given_X_when_Y_should_Z`), but **stay consistent within a file**. Imperative `test_foo` / `does_bar` names are not the convention here.
 
+### Prove a test can fail, before trusting it

Review Comment:
   warning: the canonical `given_invalid_state_should_start_fresh` at line 139 still tells authors to assert default state, but a source can refuse to serve instead, as `http_source` does. loosen it or name the alternative.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2405 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {

Review Comment:
   warning: no `.fallback` here, so a mistyped path gets axum's empty 404 and a wrong method an empty 405, while the README promises `{"error":"not found"}`. add a fallback that returns that shape.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,344 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts**, so set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, applied by the handlers rather than an extractor. Routing wins over it: an oversized POST to an unknown or revoked path answers 404 without the body being read. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie`, because forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+Env overrides reach top-level fields only, and only under the local config provider. `IGGY_CONNECTORS_SOURCE_<KEY>_PLUGIN_CONFIG_<FIELD>` sets one field of this table; the suffix is taken whole, so a nested attempt such as `..._ENDPOINTS_0_AUTH_SECRET` becomes the flat key `endpoints_0_auth_secret` and is ignored. Endpoint secrets therefore stay in TOML or go through the management API.
+
+Values are coerced before they are deserialized: `true`/`false` become booleans and anything that parses as a number becomes one. So `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` hands a JSON number to a string field and fails the whole configuration parse, with an error that does not name the field. Quote such values into non-numeric form, or set them in TOML.
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+`http_sink` calls its equivalent knob `max_payload_size_bytes`. The names differ deliberately: the sink's bounds an outgoing payload, this one bounds an accepted request.
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"too many requests"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | TCP peer address. Behind the load balancer this README recommends, that is the proxy, not the sender; forward `X-Forwarded-For` to see the original client |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 202
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only: a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |

Review Comment:
   warning: this table is missing 415, 422 and 507, and the 400 and 409 rows omit the unused-secret refusal, the 256-byte reason cap, and both new rotate refusals.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5364977008

   Rebased onto master and followed up on `af9ce9548` (#3855, source batch acknowledgments), which landed after this PR was opened and changes what this connector owes the runtime.
   
   `on_batch_result` has a default no-op in the `Source` trait, so this compiled and stayed quiet, but the default is documented as suitable only for sources with no staged or destructive work. `poll()` here drains the crossfire bridge destructively, so a NACK had nothing to act on: the events existed nowhere else and were simply gone. The connector now holds each batch until the runtime acks it and replays it on the next `poll()` otherwise, which is what lets it recover a failed send instead of absorbing it.
   
   Nothing is ever abandoned. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 the handlers return once the bridge fills, which senders retry. Dropping a staged batch would trade that bounded, visible backpressure for silent loss that grows with the length of the outage. The usual case for a give-up bound does not apply here either: oversized bodies are rejected with 413 before a handler runs, headers are clamped on accept, and `Schema::Raw` cannot fail to decode, so a permanently undeliverable batch is not reachable from the accept path.
   
   Two existing poll tests were asserting the pre-ack behaviour by polling twice without acknowledging, and now ack between the two. Four new tests cover replay on NACK, release on ACK, an empty state-only batch not staging a replay, and the never-abandon property itself so it cannot be quietly reversed.
   
   **One thing that needs a decision outside this PR: #3941.** The SDK stops a source after five consecutive NACKs, which is about 1.5s of backoff plus five send rounds, so roughly two seconds of broker unavailability ends the poll task. That is correct for a source that can re-read its cursor and wrong for this one, whose bridge is in memory: the listener keeps accepting, the bridge fills to `buffer_capacity`, and a restart loses up to 10,000 events that already received a 200. The stop is also unobservable, since the runtime's forwarding loop stays parked and `iggy_connectors_sources_running` keeps counting the source.
   
   There is a loophole that would let a plugin survive this (an empty batch always acks, which resets the breaker's counter) and I have deliberately not used it, because it defeats an SDK safety mechanism from inside a plugin. The README states the residual window and points at #3941 rather than working around it here.
   
   `README.md`'s producer-failure loss window was also stale: it said there is no feedback channel back to the handler, which #3855 made false.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984892094


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only
+                .store(state.is_some(), Ordering::Release);
+            state
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        self.last_batch_carried_state
+            .store(state.is_some(), Ordering::Release);
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free.
+    ///
+    /// A Nack does not mean neither happened. The runtime NACKs a batch it sent
+    /// successfully but whose state it could not persist, and the SDK NACKs on
+    /// its own result timeout while that send may still have landed. Holding
+    /// the copy and replaying it is therefore at-least-once by construction:
+    /// the alternative, dropping it, would turn every one of those into
+    /// silent loss.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();

Review Comment:
   Fixed in `fix(connectors): let the flush backoff and the poll order see what happened`, together with `lib.rs:954` since they are the same machine.
   
   The Ack now clears the backoff only when the batch that was acked carried the flush. `on_nack` already applied exactly this rule, and its comment even gives the reason, that a NACK unrelated to the state store should not spend the backoff budget. Only the Ack side was missing it, so the asymmetry was the whole bug.
   
   Your point about the default file backend is the part that made me treat this as more than tidiness. `is_latched` is false unconditionally for `File`, so a read-only mount or a full disk gives precisely the alternating pattern, and with the delay pinned at attempt zero that is one failed write per poll.
   
   One thing I found next to it and fixed in the same commit. The backoff's own doc comment said a store that stays latched still ends in the SDK stopping the source. That holds only on an idle gateway, where every batch is the flush so its refusals are consecutive. Under traffic `apply_batch_result` stores zero into `consecutive_nacks` on every Ack, so they are never consecutive and the source runs on indefinitely. Fixing the counter does not change that, it only spaces the retries out, so the comment now says which case ends and which does not, and leaves #3941 as the subject for the rest.
   
   The test nacks a state-only batch, then acks a batch of traffic, and asserts the counter is still one. Reverting the fix turns it red.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5160291323

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434543451

   Three more commits since I marked this ready, so please review `ca3d240fb` rather than `e48b8356a`. I had left these three as deferred, and on reflection that was the wrong call: two are defects in this crate, and "it needs a refactor" is not a reason to hand you known-broken code.
   
   **The named path authorizes before it reads the body** (`93f648c00`). This is the same ordering you flagged on the admin listener, and I fixed it there and left it on the public one. axum runs extractors before the handler body, so taking `Bytes` meant an unauthenticated caller who guessed the operator-chosen `topic_path` could make the process buffer up to `max_body_size_bytes` before receiving its 401, with no concurrency limit above it. The handler now takes the request whole, resolves the route, checks the bearer token, and only then reads the body, applying the cap itself since the extractor that carried `DefaultBodyLimit` is gone. Two tests discriminate the ordering: unauthenticated plus oversized body must answer 401, not 413. The secret paths keep their extractor deliberately, since HMAC signs the body and has to read it to verify, and there the endpoint id is itself a 128-bit secret.
   
   **Routes and instances publish as one value** (`ca3d240fb`). They were two `ArcSwap` stores, so a reader could land between them and resolve a request against the old table while holding the new instance set. On a departure that routes into a bridge nobody drains, and readiness could answer ok from a table that no longer matched. The window is nanoseconds and the code acknowledged the wider version of the race, but one `Published` value makes it unrepresentable rather than merely unlikely, and `handle_health` now reads both from a single guard.
   
   Same commit: a failed `to_connector_state` re-armed the dirty flag *and* re-posted the notify permit, which makes the next poll immediate. Nothing about the registry has changed by then, so it fails identically and re-arms, spinning the poll task through a full FFI round trip and one error line per iteration with no exit. Serializing a `BTreeMap` of endpoints is effectively infallible so the trigger is remote, but a loop with no exit is not worth leaving standing. The flag still goes back; the self-wake does not.
   
   **Shutdown bookkeeping and gauges are self-reconciling** (`632dfbd8b`). `leave` counted the instances it hoped to publish rather than the ones it did, and `publish` is all-or-nothing, so on its failure branch the next `leave` would see two instances, compute one remaining, and never reach the shutdown branch, leaving both ports bound for the process lifetime. Gauges are now cleared and rebuilt from the live set on each scrape, which removes the race between a departure and a concurrent scrape; that made `forget_instance` redundant, so it is gone rather than left advertising a guarantee it no longer provided.
   
   Everything is mutation-checked and 147 unit tests plus the six `connectors::http::http_source` integration tests pass against a real server and runtime.
   
   Two things I still have not touched, and both are genuinely outside this crate: `close()` has no flush hook, which is the `Source` trait's shape rather than something this connector can fix, and the `setup_source_producer` cleanup asymmetry in `manager/source.rs` that you flagged as not mine. Say the word on that second one and I will send it as its own PR.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5593336094

   /ready


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5593336277

   /request-review @hubcio


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984377422


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();

Review Comment:
   Agreed, and it is the worse of the two because it needs nothing to go wrong. Fixed in the same commit, `fix(connectors): frame the state file so a short read cannot fail open`.
   
   `restore` now warns when it starts with static endpoints and no registry was presented, saying what that means: an empty state file cannot be told apart from a first boot here, so if the instance ever had revocations they are gone and every revoked static endpoint is serving again. Static count zero still logs `info`, since there is nothing to put back.
   
   I will be straight about what that is worth. It is a diagnostic, not a guard, and there is nothing to fail closed on, because the plugin genuinely cannot tell the two cases apart. This crate has no log capture in its tests, so nothing asserts the line itself; what is tested is the behaviour around it, that restore still succeeds on the static config alone.
   
   `README.md` now says truncating the state file is the same act as deleting it rather than a gentler one, names the outcome, and says a corrupt file is refused instead so the two are not confused.
   
   Left alone on purpose: `state/http.rs:255-257` treating a zero-length body as valid state while the file provider treats it as no state. You said aligning them belongs in the runtime and I agree, it is not this plugin's call to make.
   
   The restart path is covered end to end by `dynamic_endpoint_survives_connector_restart` and `revoked_static_endpoint_stays_revoked_across_restart` against a real server, and both pass on the new format.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984894571


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only

Review Comment:
   Fixed in `fix(connectors): let the flush backoff and the poll order see what happened`, in one change with `lib.rs:987` as you suggested.
   
   The flip is keyed on the arm that won now, not on what it produced. A flush that wins and then declines has still spent that poll's turn: its permit is gone and `recv()` never ran, so the bridge is owed the next one whether or not any state came out.
   
   Your reachability argument is what made this worth doing rather than noting. It needs no panic and no poisoning, just an ordinary `try_mutate_registry` holding the writer across a registry clone and a `validate`, and the decline arm re-posting the permit is what makes it sustain itself rather than miss once.
   
   On the test, I did something slightly different from the mechanism you described and want to flag it rather than let it pass as equivalent. Reproducing the contended `try_lock` means holding a `std::sync::MutexGuard` across `poll().await`, which trips `clippy::await_holding_lock`, and silencing that felt worse than choosing a different way in. So the test drives the same line with a surplus permit, which reaches the decline through `registry_dirty` being false rather than through the lock. Same arm, same store, and it is deterministic. The comment names the contended path as the other route so the next reader knows the fix covers both.
   
   Reverting the fix turns it red: the second poll comes back with no messages because the flush arm took its turn again.
   
   Worth recording that the first mutant I wrote to check that did not compile, since dropping the new variable left it unused under `-D warnings`, and a mutant that does not compile looks exactly like a test that passed. The one above is a compiling mutant.
   
   205 unit tests, and all 6 http_source integration tests pass.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5549383875

   Round four is answered. Head is `5c58c6972`, rebased on master, 164 unit tests and all 6 `connectors::http::http_source` integration tests green, plus fmt, clippy at both feature sets, `cargo sort`, taplo, `--locked` and markdownlint.
   
   61 of the 65 findings are in, as eleven commits:
   
   | Commit | What |
   | --- | --- |
   | `e55572c23` | **critical** `state.rs` static resurrection |
   | `31244e3c6` | forwarded header overwriting gateway metadata |
   | `395ff963d` | three management API gaps |
   | `d280015b5` | registry ceiling and tombstone reclamation |
   | `0bf753f1c` | admin-token placeholder collision in the examples |
   | `b8ad97562` | the NACK contract and five sizing claims |
   | `3ac3e8619` | lifecycle and liveness, seven findings |
   | `d4efca998` | request path, six findings |
   | `0e532955e` | three doc comments my own commits had displaced |
   | `54d960d1c` | ten simplifications, net -68 lines |
   | `5c58c6972` | stable message id and the naming nits |
   
   ## Five things you should not have to find in the diff
   
   **1. The registry ceiling is not the tombstone purge route you sketched.** It is a cap plus automatic reclamation of the oldest revoked **dynamic** tombstones, never static ones. The asymmetry is what makes it safe: a dynamic endpoint exists only in the registry, so its path 404s whether the tombstone is there or not, and the tombstone carries audit value rather than a guarantee. A static one outranks a TOML entry that still declares it, so reclaiming it would resurrect it. This avoids new admin API surface and cannot brick registration the way a bare cap would. Say the word if you would rather have the route.
   
   **2. Revoke answers 202.** You offered that or an ack generation counter; this took the simpler one and points at `GET /admin/endpoints/{id}`.
   
   **3. The state-flush backoff shape is mine.** You asked for a delay or an attempt cap without specifying. It is first-retry-immediate, then 250ms doubling to an 8s ceiling, cleared on any Ack. Worth saying that the obvious alternative was considered and rejected: an empty batch always acks and would reset the SDK breaker, which defeats an SDK safety mechanism from inside one plugin.
   
   **4. `management.rs:108` is implemented in half, because the other half was already there.** `#[serde(deny_unknown_fields)]` is on all three request structs (`RegisterRequest`, `RotateRequest`, `RevokeRequest`), with `given_unknown_field_when_registered_should_reject` covering it, so a misspelled key is rejected at parse and cannot mint an unauthenticated endpoint. Only an *omitted* `auth_type` defaults to `none`, which is the deliberate model. The valid half, rejecting a secret supplied with `auth_type: none`, is in.
   
   **5. `serialize_secret_to_state` stays.** You are right that it is `iggy_common::serialize_optional_secret` line for line. Its doc comment names that helper and explains the duplication: it keeps the one place this crate deliberately writes a secret greppable and unreachable by accident, which is the same reason `HttpSourceConfig` has no `Serialize` at all. Happy to delete it if you would rather have the shared one, but I did not want to remove a recorded decision silently.
   
   ## Two deferred, both larger than their labels
   
   - **Returning the `Arc` instead of a cloned instance name** is plumbing through both outcome functions for one clone per request.
   - **Biasing the poll `select!`** needs the guard you name in the same sentence, so two state-only batches cannot run back to back and a mutation flood cannot starve `recv()`. That is a scheduling change and wants a test that can observe starvation.
   
   **Dropping the `submitted` field** is also left for its own change. It rewrites how durability is reported, you name two windows where the flag and the dirty bit disagree, and `close()` now reports an unsubmitted count that would have no per-endpoint basis without it.
   
   ## Two findings worth reporting back
   
   **The `free_port` race is real and it fired while I was fixing it.** One suite run failed on an unrelated test, then passed alone and three full runs after. nextest gives each test its own process, so no in-process bookkeeping closes the window between the release and the real bind. `open()` retries on address-in-use, and the integration fixture holds both listeners until both ports are chosen.
   
   **Messages had no stable id.** Everything went out as wire id 0, so a batch the runtime NACKed and `poll()` re-sent gave a consumer nothing to dedupe on. Each request now carries a random 128-bit id minted at accept time and kept across replay. That closes the replay half of the duplicate window; a sender retrying because it never saw the 200 is a genuinely new request, and the README separates the two now.
   
   ## The four outside the diff are still yours
   
   All four verified against master rather than taken on trust:
   
   1. **critical, `runtime/src/manager/source.rs:232-241`** confirmed: the restart path returns from `setup_source_producer(..).await?` with no `iggy_source_close` after `init_source` succeeded, while `runtime/src/source.rs:245-262` cleans up on the identical failure. This is the same follow-up you flagged as not mine in round two.
   2. **`sdk/src/source.rs:297-338`** confirmed: shadowing does not drop, so the `ProducedMessages` binding stays resident beside the serialized copy. `drop(messages)` at :338 releases only the latter.
   3. **`sdk/src/source.rs:383-393`** confirmed, including the consequence: the only `source.close()` is at `sdk/src/source.rs:211`, inside the FFI `iggy_source_close` path, which a self-stop never reaches.
   4. **`_build_rust_artifacts.yml:49`** confirmed, and your count is exact: 21 connector crates, 10 listed, 9 others missing besides this one.
   
   Happy to take any of them as separate PRs, including the runtime one, if you want them off your list.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3982737646


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2189 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::admit_endpoint;
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies. Written out here
+            // once, these checks drifted: config admitted an `auth_type: none`
+            // carrying a secret, which then rode into the state file in clear
+            // where nothing reads it, and an `expires_at` already past, which
+            // 404s forever with only the serving count as a hint.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(

Review Comment:
   Fixed in `6c5f312f9` "stop a passed expiry refusing the whole instance".
   
   One deviation worth naming rather than leaving you to find: you asked to scope the check to the endpoint the way `restore` does. Shipped is `auth::Admission::{Creating,Existing}`, with `validate()` passing `Existing` so the config path skips the clock rule entirely. Same outcome, different shape, and the narrower fix was the alternative.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2405 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+/// A request that resolved to no instance is still metered, under [`UNROUTED`],
+/// which is where a scan for live endpoint ids shows up.
+fn instance_label(instance: Option<&Arc<SharedState>>) -> &str {
+    instance.map_or(UNROUTED, |instance| instance.instance_name.as_str())
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) = named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// The instance the request resolved to, for the caller to label metrics with.
+/// Returning the `Arc` the lookup already produced rather than a copy of its
+/// name keeps the label allocation-free on the request path; `None` is a
+/// request that resolved to no instance, counted under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands them over owned, so nothing is cloned to survive the
+    // body being taken.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+        };
+        Arc::clone(instance)
+    };
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            Some(instance),
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (Some(instance), oversized_body_response(&error)),
+    };
+    let response = enqueue(

Review Comment:
   Fixed in `829959d16` "re-resolve the named path after its body too", which is your prescription: re-lookup plus `Arc::ptr_eq`, copied from the secret path. `b2653e81c` moved the bearer check ahead of the body read on the same path.
   
   Since then the refusal became a 503 rather than a 404 (`eb65777cb`, then `b4be8bf94` for the wording), because this arm covers both a withdrawn path and a handover and the caller had already authenticated. The `ptr_eq` half is pinned by a test whose rival instance holds a live bridge, so removing the guard answers `200 OK` rather than a 503 that a disconnected bridge would also produce.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2405 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {

Review Comment:
   Fixed in `e9dd93691` "answer unrouted public requests in this API's error shape".
   
   The fallback is on the public router only. The admin router keeps axum's bare fallback deliberately, and a test pins that, since the admin listener has no unauthenticated callers to keep uninformed.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,344 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts**, so set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, applied by the handlers rather than an extractor. Routing wins over it: an oversized POST to an unknown or revoked path answers 404 without the body being read. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie`, because forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+Env overrides reach top-level fields only, and only under the local config provider. `IGGY_CONNECTORS_SOURCE_<KEY>_PLUGIN_CONFIG_<FIELD>` sets one field of this table; the suffix is taken whole, so a nested attempt such as `..._ENDPOINTS_0_AUTH_SECRET` becomes the flat key `endpoints_0_auth_secret` and is ignored. Endpoint secrets therefore stay in TOML or go through the management API.
+
+Values are coerced before they are deserialized: `true`/`false` become booleans and anything that parses as a number becomes one. So `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` hands a JSON number to a string field and fails the whole configuration parse, with an error that does not name the field. Quote such values into non-numeric form, or set them in TOML.
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+`http_sink` calls its equivalent knob `max_payload_size_bytes`. The names differ deliberately: the sink's bounds an outgoing payload, this one bounds an accepted request.
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"too many requests"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | TCP peer address. Behind the load balancer this README recommends, that is the proxy, not the sender; forward `X-Forwarded-For` to see the original client |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 202
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only: a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |

Review Comment:
   Fixed in `e9dd93691`. The table gained 415, 422 and 507, and the 400 and 409 rows now carry the unused-secret refusal, the 256-byte reason cap and both rotate refusals.
   
   415 was pinned by a new test before it was documented, rather than the other way round.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,344 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |

Review Comment:
   Fixed in `e9dd93691`. The max column carries 1000000, 100000 and 67108864, each checked against the const rather than the prose.
   
   `f8b1c4283` later tied the three `Inadmissible` ceiling messages to their consts with a test, after finding the existing ceiling tests could not catch that drift: they build their oversized inputs from the consts, so raising one moves the test and the code together.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2189 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::admit_endpoint;
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies. Written out here
+            // once, these checks drifted: config admitted an `auth_type: none`
+            // carrying a secret, which then rode into the state file in clear
+            // where nothing reads it, and an `expires_at` already past, which
+            // 404s forever with only the serving count as a hint.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                unix_now_seconds(),
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only
+                .store(state.is_some(), Ordering::Release);
+            state
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        self.last_batch_carried_state
+            .store(state.is_some(), Ordering::Release);
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free.
+    ///
+    /// A Nack does not mean neither happened. The runtime NACKs a batch it sent
+    /// successfully but whose state it could not persist, and the SDK NACKs on
+    /// its own result timeout while that send may still have landed. Holding
+    /// the copy and replaying it is therefore at-least-once by construction:
+    /// the alternative, dropping it, would turn every one of those into
+    /// silent loss.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();
+                self.shared.clear_state_flush_backoff();
+                Ok(())
+            }
+            source::SourceBatchResult::Nack => self.on_nack(),
+        }
+    }
+
+    async fn close(&mut self) -> Result<(), Error> {
+        // Counted before `leave`, which is what folds it into
+        // `http_source_dropped_on_close_total` alongside the bridge. Leaving it
+        // to a log line under-reported shutdown loss by up to `max_batch_size`.
+        let staged_dropped = match self.lock_staged().take() {
+            Some(staged) => {
+                warn!(
+                    "Dropping {} unacknowledged messages for {CONNECTOR_NAME} connector ID: {}",
+                    staged.messages.len(),
+                    self.shared.id
+                );
+                staged.messages.len() as u64
+            }
+            None => 0,
+        };
+        // A mutation made after the last poll never reached the runtime, and
+        // there is no poll left to carry it. The endpoint is live again after
+        // the restart while the admin API reported the change applied, so this
+        // is the only record that it did not stick. `close()` has no way to
+        // flush it: state reaches the runtime only as the return value of
+        // `poll()`.
+        if self.shared.has_pending_state() {
+            warn!(
+                "Closing {CONNECTOR_NAME} connector ID: {} with an unflushed registry: {} change(s) not submitted, so a change made since the last poll will not survive the restart",
+                self.shared.id,
+                self.shared.pending_change_count()
+            );
+        }
+        // The SDK stops the poll task before calling this, so anything still
+        // in the bridge is already unreachable. Deregistering first is what
+        // stops new requests from being accepted into a queue nobody drains.
+        server::leave(&self.shared, staged_dropped).await;
+        info!("Closed {CONNECTOR_NAME} connector ID: {}", self.shared.id);
+        Ok(())
+    }
+}
+
+/// Backoff before re-posting a state flush the runtime refused.
+///
+/// The first retry is immediate, so an isolated refusal costs nothing. Past
+/// that it doubles to an eight second ceiling, which is inside the SDK's
+/// result timeout, so a store that recovers is picked up promptly. A store
+/// that stays latched still ends in the SDK stopping the source; that is
+/// #3941's subject, not something this connector can fix from the inside.
+fn state_flush_retry_delay(attempt: u32) -> Duration {
+    match attempt {
+        0 => Duration::ZERO,
+        n => Duration::from_millis(250u64 << (n - 1).min(5)),
+    }
+}
+
+fn default_admin_listen_addr() -> String {
+    DEFAULT_ADMIN_LISTEN_ADDR.to_string()
+}
+
+fn default_max_body_size_bytes() -> usize {
+    DEFAULT_MAX_BODY_SIZE_BYTES
+}
+
+fn default_buffer_capacity() -> usize {
+    DEFAULT_BUFFER_CAPACITY
+}
+
+fn default_max_batch_size() -> usize {
+    DEFAULT_MAX_BATCH_SIZE
+}
+
+fn default_hmac_header() -> String {
+    DEFAULT_HMAC_HEADER.to_string()
+}
+
+fn default_hmac_prefix() -> String {
+    DEFAULT_HMAC_PREFIX.to_string()
+}
+
+fn default_true() -> bool {
+    true
+}
+
+/// Fixtures shared by the routing and state test modules.
+#[cfg(test)]
+pub(crate) mod test_support {
+    use super::*;
+
+    pub const ENDPOINT_ONE: &str = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d";
+    pub const ENDPOINT_TWO: &str = "b4092d3fa1c85e6b7d0f2a1c3e4b5d6a";
+
+    pub fn endpoint_id(raw_id: &str) -> EndpointId {
+        raw_id.parse().expect("test endpoint id must be valid")
+    }
+
+    pub fn static_endpoint(raw_id: &str) -> StaticEndpointConfig {
+        StaticEndpointConfig {
+            endpoint_id: endpoint_id(raw_id),
+            auth_type: EndpointAuthType::HmacSha256,
+            auth_secret: Some(SecretString::from("whsec_static")),
+            hmac_header: DEFAULT_HMAC_HEADER.to_string(),
+            hmac_prefix: DEFAULT_HMAC_PREFIX.to_string(),
+            expires_at: None,
+        }
+    }
+
+    pub fn config(topic_path: Option<&str>, endpoint_ids: &[&str]) -> HttpSourceConfig {
+        HttpSourceConfig {
+            listen_addr: "127.0.0.1:9090".to_string(),
+            admin_listen_addr: DEFAULT_ADMIN_LISTEN_ADDR.to_string(),
+            max_body_size_bytes: DEFAULT_MAX_BODY_SIZE_BYTES,
+            buffer_capacity: DEFAULT_BUFFER_CAPACITY,
+            max_batch_size: DEFAULT_MAX_BATCH_SIZE,
+            topic_path: topic_path.map(str::to_string),
+            instance_name: None,
+            auth_bearer_token: None,
+            management_token: None,
+            include_http_metadata: true,
+            forward_headers: Vec::new(),
+            endpoints: endpoint_ids
+                .iter()
+                .map(|raw_id| static_endpoint(raw_id))
+                .collect(),
+        }
+    }
+
+    /// Reserves an ephemeral port and hands it back. Every test that binds
+    /// needs its own, because the listener registry is process-global and the
+    /// test binary runs its cases in parallel.
+    pub fn free_port() -> u16 {
+        std::net::TcpListener::bind("127.0.0.1:0")
+            .expect("the loopback interface must offer a port")
+            .local_addr()
+            .expect("a bound listener has an address")
+            .port()
+    }
+
+    /// No connection pooling: an idle keep-alive socket would hold graceful
+    /// shutdown open until the timeout and slow every teardown to a crawl.
+    pub fn client() -> reqwest::Client {
+        reqwest::Client::builder()
+            .pool_max_idle_per_host(0)
+            .build()
+            .expect("the test client must build")
+    }
+
+    /// Builds one instance's shared state through the real constructor. The
+    /// source itself is dropped, taking the bridge receiver with it: routing
+    /// and state tests resolve and mutate, they never send.
+    pub fn instance(id: u32, topic_path: Option<&str>, endpoint_ids: &[&str]) -> Arc<SharedState> {
+        let source = HttpSource::new(id, config(topic_path, endpoint_ids), None);
+        Arc::clone(&source.shared)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::{ENDPOINT_ONE, ENDPOINT_TWO};
+    use iggy_connector_sdk::source::SourceBatchResult;
+
+    fn minimal_config_json() -> &'static str {
+        r#"{"listen_addr": "0.0.0.0:9090"}"#
+    }
+
+    fn parse(config_json: &str) -> HttpSourceConfig {
+        serde_json::from_str(config_json).expect("config must deserialize")
+    }
+
+    #[test]
+    fn given_minimal_config_when_deserialized_should_apply_defaults() {
+        let config = parse(minimal_config_json());
+        assert_eq!(config.admin_listen_addr, DEFAULT_ADMIN_LISTEN_ADDR);
+        assert_eq!(config.max_body_size_bytes, DEFAULT_MAX_BODY_SIZE_BYTES);
+        assert_eq!(config.buffer_capacity, DEFAULT_BUFFER_CAPACITY);
+        assert_eq!(config.max_batch_size, DEFAULT_MAX_BATCH_SIZE);
+        assert!(config.include_http_metadata);
+        assert!(config.topic_path.is_none());
+        assert!(config.auth_bearer_token.is_none());
+        assert!(config.management_token.is_none());
+        assert!(config.forward_headers.is_empty());
+        assert!(config.endpoints.is_empty());
+    }
+
+    #[test]
+    fn given_minimal_config_when_validated_should_accept() {
+        assert!(parse(minimal_config_json()).validate().is_ok());
+    }
+
+    #[test]
+    fn given_unparsable_listen_addr_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "not-an-address"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("listen_addr")
+        ));
+    }
+
+    #[test]
+    fn given_zero_buffer_capacity_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "buffer_capacity": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("buffer_capacity")
+        ));
+    }
+
+    #[test]
+    fn given_oversized_sizing_values_when_validated_should_reject() {
+        for (field, json) in [
+            (
+                "buffer_capacity",
+                r#"{"listen_addr": "0.0.0.0:9090", "buffer_capacity": 1000001}"#,
+            ),
+            (
+                "max_batch_size",
+                r#"{"listen_addr": "0.0.0.0:9090", "max_batch_size": 100001}"#,
+            ),
+            (
+                "max_body_size_bytes",
+                r#"{"listen_addr": "0.0.0.0:9090", "max_body_size_bytes": 67108865}"#,
+            ),
+        ] {
+            assert!(
+                matches!(
+                    parse(json).validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains(field)
+                ),
+                "{field} had a floor and no ceiling"
+            );
+        }
+    }
+
+    #[test]
+    fn given_unbuildable_buffer_capacity_when_constructed_should_clamp_not_panic() {
+        let mut config = test_support::config(None, &[]);
+        config.buffer_capacity = usize::MAX;
+
+        // `new` builds the crossfire ring, and crossfire asserts on a capacity
+        // this large. That panic would unwind out of `iggy_source_open`, which
+        // is `extern "C"` with no `catch_unwind`, aborting the whole connectors
+        // process. The SDK builds the source before it calls `open`, so
+        // `validate` is not what stands between a typo and that abort.
+        let source = HttpSource::new(1, config, None);
+
+        assert!(
+            source.shared.sender.try_send(queued("one")).is_ok(),
+            "the clamped ring must still be usable"
+        );
+        assert!(
+            matches!(
+                source.shared.config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("buffer_capacity")
+            ),
+            "and open() must still report the misconfiguration rather than serve it"
+        );
+    }
+
+    #[test]
+    fn given_reserved_instance_name_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "instance_name": "unrouted"}"#);
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("reserved")
+            ),
+            "requests matching no route are metered under this name, and that series is the endpoint-id scan signal"
+        );
+    }
+
+    #[test]
+    fn given_config_endpoints_the_api_would_refuse_when_validated_should_refuse_them_too() {
+        // Both were admitted from TOML and refused by the management API, which
+        // is the drift the shared rule exists to stop. The unused secret rides
+        // into the state file in clear where nothing ever reads it; the past
+        // expiry 404s forever with only the serving count as a hint.
+        for (reason, json) in [
+            (
+                "takes no auth_secret",
+                r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                    {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none", "auth_secret": "whsec_unused"}
+                ]}"#,
+            ),
+            (
+                "already past",
+                r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                    {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none", "expires_at": 1}
+                ]}"#,
+            ),
+        ] {
+            let config = parse(json);
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains(reason)
+                ),
+                "config must refuse what the management API refuses: {reason}"
+            );
+        }
+    }
+
+    #[test]
+    fn given_duplicate_endpoint_id_when_validated_should_reject() {
+        let config = parse(
+            r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none"},
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "none"}
+            ]}"#,
+        );
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("more than once")
+            ),
+            "the registry is a map, so the second block would silently last-win"
+        );
+    }
+
+    #[test]
+    fn given_invalid_hmac_header_when_validated_should_reject() {
+        let config = parse(
+            r#"{"listen_addr": "0.0.0.0:9090", "endpoints": [
+                {"endpoint_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "auth_type": "hmac-sha256",
+                 "auth_secret": "whsec", "hmac_header": "not a header"}
+            ]}"#,
+        );
+        assert!(
+            matches!(
+                config.validate(),
+                Err(Error::InvalidConfigValue(message)) if message.contains("hmac_header")
+            ),
+            "an invalid name makes HeaderMap::get return None, so every signed request 401s forever"
+        );
+    }
+
+    #[test]
+    fn given_topic_path_with_slash_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "topic_path": "a/b"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("topic_path")
+        ));
+    }
+
+    #[test]
+    fn given_endpoint_with_auth_but_no_secret_when_validated_should_reject() {
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256"
+                }]
+            }"#,
+        );
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("auth_secret")
+        ));
+    }
+
+    #[test]
+    fn given_endpoint_config_when_deserialized_should_apply_hmac_defaults() {
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256",
+                    "auth_secret": "whsec_test"
+                }]
+            }"#,
+        );
+        let endpoint = &config.endpoints[0];
+        assert_eq!(endpoint.hmac_header, DEFAULT_HMAC_HEADER);
+        assert_eq!(endpoint.hmac_prefix, DEFAULT_HMAC_PREFIX);
+        assert_eq!(endpoint.auth_type.hmac_algorithm(), Some(hmac::HMAC_SHA256));
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn given_zero_max_batch_size_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "max_batch_size": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("max_batch_size")
+        ));
+    }
+
+    #[test]
+    fn given_zero_max_body_size_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "max_body_size_bytes": 0}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("max_body_size_bytes")
+        ));
+    }
+
+    #[test]
+    fn given_unparsable_admin_addr_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "admin_listen_addr": "nope"}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("admin_listen_addr")
+        ));
+    }
+
+    #[test]
+    fn given_empty_instance_name_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "instance_name": ""}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("instance_name")
+        ));
+    }
+
+    #[test]
+    fn given_oversized_instance_name_when_validated_should_reject() {
+        // It becomes a HeaderKey, and Iggy caps those at 255 bytes. Without
+        // this check the identity header would vanish from every message.
+        let long_name = "n".repeat(256);
+        let config = parse(&format!(
+            r#"{{"listen_addr": "0.0.0.0:9090", "instance_name": "{long_name}"}}"#
+        ));
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("instance_name")
+        ));
+    }
+
+    #[test]
+    fn given_invalid_forward_header_when_validated_should_reject() {
+        // `new()` silently filters entries that fail to resolve, on the stated
+        // assumption that validate() rejects them first. That is the test.
+        let config =
+            parse(r#"{"listen_addr": "0.0.0.0:9090", "forward_headers": ["not a header"]}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("forward_headers")
+        ));
+    }
+
+    #[test]
+    fn given_empty_endpoint_secret_when_validated_should_reject() {
+        // An empty key is valid for HMAC, so accepting one would advertise a
+        // second factor that anyone holding the URL can compute.
+        let config = parse(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{
+                    "endpoint_id": "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d",
+                    "auth_type": "hmac-sha256",
+                    "auth_secret": ""
+                }]
+            }"#,
+        );
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("auth_secret")
+        ));
+    }
+
+    #[test]
+    fn given_empty_management_token_when_validated_should_reject() {
+        let config = parse(r#"{"listen_addr": "0.0.0.0:9090", "management_token": ""}"#);
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("management_token")
+        ));
+    }
+
+    #[test]
+    fn given_credential_forward_header_when_validated_should_reject() {
+        for header in ["Authorization", "cookie", "PROXY-AUTHORIZATION"] {
+            let config = parse(&format!(
+                r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{header}"]}}"#
+            ));
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains("credential")
+                ),
+                "{header} would be copied onto every message and persisted in the log"
+            );
+        }
+    }
+
+    #[test]
+    fn given_first_refused_flush_when_retried_should_not_delay() {
+        // An isolated refusal must cost nothing: the store may already be
+        // healthy again by the next poll, and delaying every one of them would
+        // hold a revocation back for no reason.
+        assert_eq!(state_flush_retry_delay(0), Duration::ZERO);
+    }
+
+    #[test]
+    fn given_repeated_refusals_when_retried_should_back_off_to_a_ceiling() {
+        // Growth is what stops a latched store burning the SDK's five-NACK
+        // budget in a tight loop; the ceiling is what stops a recovered store
+        // waiting minutes to be noticed.
+        let delays: Vec<Duration> = (1..=10).map(state_flush_retry_delay).collect();
+        for pair in delays.windows(2) {
+            assert!(
+                pair[1] >= pair[0],
+                "backoff must never shrink, got {:?} then {:?}",
+                pair[0],
+                pair[1]
+            );
+        }
+        assert_eq!(delays[0], Duration::from_millis(250));
+        assert_eq!(
+            *delays.last().expect("range is not empty"),
+            Duration::from_secs(8),
+            "the delay must stop growing well inside the SDK's result timeout"
+        );
+    }
+
+    #[test]
+    fn given_reserved_metadata_forward_header_when_validated_should_reject() {
+        // `message_headers` inserts the metadata first and forwarded headers
+        // into the same map, so without this the sender picks the value the
+        // pipeline trusts. Mixed case because HTTP header names are
+        // case-insensitive and the sender chooses the casing.
+        for header in [
+            INSTANCE_HEADER,
+            REMOTE_ADDR_HEADER,
+            RECEIVED_AT_HEADER,
+            "IGGY_HTTP_REMOTE_ADDR",
+        ] {
+            let config = parse(&format!(
+                r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{header}"]}}"#
+            ));
+            assert!(
+                matches!(
+                    config.validate(),
+                    Err(Error::InvalidConfigValue(message)) if message.contains("reserved")
+                ),
+                "{header} would let the sender overwrite the gateway's own metadata"
+            );
+        }
+    }
+
+    #[test]
+    fn given_oversized_forward_header_when_validated_should_reject() {
+        // Valid as an HTTP name, too long to become a HeaderKey. Rejected here
+        // rather than dropped later, so the operator learns the header they
+        // asked to forward would never have ridden along.
+        let long_header = "x".repeat(256);
+        let config = parse(&format!(
+            r#"{{"listen_addr": "0.0.0.0:9090", "forward_headers": ["{long_header}"]}}"#
+        ));
+        assert!(matches!(
+            config.validate(),
+            Err(Error::InvalidConfigValue(message)) if message.contains("Iggy header key")
+        ));
+    }
+
+    #[test]
+    fn given_auth_types_when_asked_for_an_algorithm_should_map_each_exactly_once() {
+        // A swapped arm would validate SHA-1 signatures with SHA-256 and
+        // reject every request the sender signs correctly.
+        assert_eq!(
+            EndpointAuthType::HmacSha256.hmac_algorithm(),
+            Some(hmac::HMAC_SHA256)
+        );
+        assert_eq!(
+            EndpointAuthType::HmacSha1.hmac_algorithm(),
+            Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY)
+        );
+        assert_eq!(EndpointAuthType::Bearer.hmac_algorithm(), None);
+        assert_eq!(EndpointAuthType::None.hmac_algorithm(), None);
+    }
+
+    #[test]
+    fn given_invalid_endpoint_id_when_deserialized_should_reject() {
+        let result = serde_json::from_str::<HttpSourceConfig>(
+            r#"{
+                "listen_addr": "0.0.0.0:9090",
+                "endpoints": [{"endpoint_id": "too-short"}]
+            }"#,
+        );
+        assert!(result.is_err(), "invalid endpoint_id must fail at parse");
+    }
+
+    /// The shipped configurations are documentation, and documentation that
+    /// no longer deserializes is worse than none.
+    #[test]
+    fn given_shipped_configs_when_parsed_should_deserialize_and_validate() {
+        for (name, raw) in [
+            ("config.toml", include_str!("../config.toml")),
+            (
+                "example_config/http_source_github.toml",
+                include_str!("../../../runtime/example_config/connectors/http_source_github.toml"),
+            ),
+            (
+                "example_config/http_source_partner.toml",
+                include_str!("../../../runtime/example_config/connectors/http_source_partner.toml"),
+            ),
+        ] {
+            let document: toml::Value =
+                toml::from_str(raw).unwrap_or_else(|error| panic!("{name} must parse: {error}"));
+            let plugin_config = document
+                .get("plugin_config")
+                .unwrap_or_else(|| panic!("{name} must carry a plugin_config table"))
+                .clone();
+            let config: HttpSourceConfig = plugin_config
+                .try_into()
+                .unwrap_or_else(|error| panic!("{name} plugin_config must deserialize: {error}"));
+            config
+                .validate()
+                .unwrap_or_else(|error| panic!("{name} must pass validation: {error}"));
+        }
+    }
+
+    fn queued(payload: &str) -> QueuedMessage {
+        QueuedMessage {
+            id: 0,

Review Comment:
   Fixed in `242a7b76b` "prove a replayed message keeps its id".
   
   `queued()` now mints a distinct non-zero id per message, and the replay test captures the ids the first poll produced and requires the replayed batch to carry the same ones in order. It also requires them non-zero, so the helper cannot drift back to the one value the server replaces. Checked by making the replay path rebuild without the id: the payload assertions still pass and the id assertion fails.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3982739213


##########
core/integration/tests/connectors/http/http_source.rs:
##########
@@ -0,0 +1,556 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use super::{POLL_ATTEMPTS, POLL_INTERVAL_MS};
+use crate::connectors::fixtures::{
+    GITHUB_ENDPOINT_ID, GITHUB_HMAC_HEADER, GITHUB_INSTANCE, HttpSourceFixture, MANAGEMENT_TOKEN,
+    PARTNER_BEARER_TOKEN, PARTNER_ENDPOINT_ID, PARTNER_INSTANCE,
+};
+use iggy::prelude::IggyClient;
+use iggy_common::MessageClient;
+use iggy_common::{Consumer, Identifier, PollingStrategy};
+use iggy_connector_sdk::api::{ConnectorStatus, SourceInfoResponse};
+use integration::harness::seeds;
+use integration::iggy_harness;
+use reqwest::{Client, StatusCode};
+use serde_json::{Value, json};
+use std::time::Duration;
+use tokio::time::sleep;
+
+const API_KEY: &str = "test-api-key";
+const RESTORED_TOKEN: &str = "token-that-must-survive-a-restart";
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn webhook_post_produces_message_to_iggy(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push","repository":"apache/iggy"}"#;
+    let response = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .header("X-GitHub-Delivery", "72d3162e-cc78-11e3-81ab-4c9367dc0958")
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST the webhook");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_1", 1).await;
+    assert_eq!(
+        String::from_utf8_lossy(&messages[0].0),
+        body,
+        "the raw request body must reach Iggy byte for byte"
+    );
+    let headers = messages[0]
+        .1
+        .as_ref()
+        .expect("HTTP metadata forwarding is enabled");
+    assert_eq!(
+        header_value(headers, "iggy_source_instance").as_deref(),
+        Some(GITHUB_INSTANCE)
+    );
+    assert_eq!(
+        header_value(headers, "X-GitHub-Delivery").as_deref(),
+        Some("72d3162e-cc78-11e3-81ab-4c9367dc0958"),
+        "the delivery id is the consumer's dedup key and must survive the FFI hop"
+    );
+}
+
+/// The secret path is covered above; nothing exercised the named one, which is
+/// the route an operator gets by setting `topic_path` and the one a typo in
+/// `auth_bearer_token` would leave open.
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn named_path_post_produces_message_to_iggy(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"deployment","environment":"staging"}"#;
+    let response = http
+        .post(fixture.named_url(seeds::names::TOPIC))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the named path");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_named", 1).await;
+    assert_eq!(
+        String::from_utf8_lossy(&messages[0].0),
+        body,
+        "the named path must deliver the raw body byte for byte, same as the secret path"
+    );
+    let headers = messages[0]
+        .1
+        .as_ref()
+        .expect("HTTP metadata forwarding is enabled");
+    assert_eq!(
+        header_value(headers, "iggy_source_instance").as_deref(),
+        Some(GITHUB_INSTANCE),
+        "and must attribute the message to the instance that owns the topic_path"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn two_instances_share_one_listener(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let github_body = r#"{"from":"github"}"#;
+    let github = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(github_body.as_bytes()),
+        )
+        .body(github_body)
+        .send()
+        .await
+        .expect("Failed to POST to the GitHub endpoint");
+    let partner_body = r#"{"from":"partner"}"#;
+    let partner = http
+        .post(fixture.webhook_url(PARTNER_ENDPOINT_ID))
+        .header("Authorization", format!("Bearer {PARTNER_BEARER_TOKEN}"))
+        .body(partner_body)
+        .send()
+        .await
+        .expect("Failed to POST to the partner endpoint");
+
+    assert_eq!(github.status(), StatusCode::OK);
+    assert_eq!(
+        partner.status(),
+        StatusCode::OK,
+        "the second instance must be reachable on the port the first one bound"
+    );
+
+    let first = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_2a", 1).await;
+    let second = poll_payloads(&client, seeds::names::TOPIC_2, "http_source_cg_2b", 1).await;
+    assert_eq!(String::from_utf8_lossy(&first[0].0), github_body);
+    assert_eq!(
+        String::from_utf8_lossy(&second[0].0),
+        partner_body,
+        "one listener, but each instance produces to its own topic"
+    );
+    assert_eq!(
+        header_value(
+            second[0].1.as_ref().expect("metadata is on by default"),
+            "iggy_source_instance"
+        )
+        .as_deref(),
+        Some(PARTNER_INSTANCE)
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn management_registered_endpoint_accepts_until_revoked(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let endpoint_id = register_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    let body = r#"{"event":"dynamic"}"#;
+    let accepted = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the registered endpoint");
+    assert_eq!(
+        accepted.status(),
+        StatusCode::OK,
+        "an endpoint registered through the API must serve without a restart"
+    );
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_3", 1).await;
+    assert_eq!(String::from_utf8_lossy(&messages[0].0), body);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{endpoint_id}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the endpoint");
+    assert_eq!(revoked.status(), StatusCode::ACCEPTED);
+
+    let after = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the revoked endpoint");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "a revocation must take effect immediately, and must not leak that the URL once worked"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn dynamic_endpoint_survives_connector_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    // Registered with a secret so the restart proves the credential survives
+    // the state round trip, not merely the endpoint id.
+    let endpoint_id = register_secured_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    // The registry only reaches the runtime once a poll carrying it has been
+    // sent, so wait for the connector to report it submitted before pulling
+    // the rug out from under it.
+    wait_for_submitted(&http, &fixture, &endpoint_id).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(
+        restarted.status().is_success(),
+        "Restart request failed: {}",
+        restarted.status()
+    );
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let authorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .header("Authorization", format!("Bearer {RESTORED_TOKEN}"))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    let unauthorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+
+    assert_eq!(
+        authorized.status(),
+        StatusCode::OK,
+        "an endpoint that only ever existed in ConnectorState must come back with the connector"
+    );
+    assert_eq!(
+        unauthorized.status(),
+        StatusCode::UNAUTHORIZED,
+        "and its secret must come back with it, not be dropped to an open endpoint"
+    );
+}
+
+/// The README's strongest security claim: a revoked endpoint must not be
+/// resurrected by a restart that re-reads the TOML still declaring it.
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn revoked_static_endpoint_stays_revoked_across_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push"}"#;
+    let before = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST before revocation");
+    assert_eq!(before.status(), StatusCode::OK);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{GITHUB_ENDPOINT_ID}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the static endpoint");
+    assert_eq!(revoked.status(), StatusCode::ACCEPTED);
+    wait_for_submitted(&http, &fixture, GITHUB_ENDPOINT_ID).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(restarted.status().is_success());
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let after = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "the tombstone must outlive the restart even though http_github.toml still declares this endpoint"
+    );
+}
+
+/// Keep-alive is off on purpose. The gateway shuts down gracefully, so an idle
+/// pooled socket holds the listener open until its shutdown timeout expires,
+/// stalling harness teardown for seconds per test.
+fn webhook_client() -> Client {
+    Client::builder()
+        .pool_max_idle_per_host(0)
+        .build()
+        .expect("Failed to build the webhook client")
+}
+
+/// The listener binds during the connector's `open()`, which happens after the
+/// runtime's own HTTP API is already answering.
+///
+/// Waits for *both* instances by name. The public `/health` answers as soon as
+/// one instance is serving, and the two open independently, so returning on the
+/// first left every later request racing the second: a post to
+/// `PARTNER_ENDPOINT_ID` would 404, and a registration against `GITHUB_INSTANCE`
+/// would come back "unknown instance", depending on which won.
+async fn wait_for_gateway(http: &Client, fixture: &HttpSourceFixture) {
+    for _ in 0..POLL_ATTEMPTS {
+        if let Ok(response) = http
+            .get(format!("{}/admin/health", fixture.admin_url()))
+            .send()
+            .await
+            && response.status() == StatusCode::OK
+            && let Ok(health) = response.json::<Value>().await
+        {
+            let joined: Vec<&str> = health["instances"]
+                .as_array()
+                .map(|instances| {
+                    instances
+                        .iter()
+                        .filter_map(|instance| instance["instance"].as_str())
+                        .collect()
+                })
+                .unwrap_or_default();
+            if joined.contains(&GITHUB_INSTANCE) && joined.contains(&PARTNER_INSTANCE) {
+                return;
+            }
+        }
+        sleep(Duration::from_millis(POLL_INTERVAL_MS)).await;
+    }
+    panic!("Both webhook gateway instances did not join in time");
+}
+
+/// Registers a bearer-guarded endpoint, so a test can prove the secret and not
+/// just the id survives whatever it does next.
+async fn register_secured_endpoint(
+    http: &Client,
+    fixture: &HttpSourceFixture,
+    instance: &str,
+) -> String {
+    let response = http
+        .post(format!("{}/admin/endpoints", fixture.admin_url()))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({
+            "instance": instance,
+            "auth_type": "bearer",
+            "auth_secret": RESTORED_TOKEN,
+        }))
+        .send()
+        .await
+        .expect("Failed to register a secured endpoint");
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let body: Value = response
+        .json()
+        .await
+        .expect("Registration must return JSON");
+    body["endpoint_id"]
+        .as_str()
+        .expect("Registration must return an endpoint id")
+        .to_string()
+}
+
+async fn register_endpoint(http: &Client, fixture: &HttpSourceFixture, instance: &str) -> String {
+    let response = http
+        .post(format!("{}/admin/endpoints", fixture.admin_url()))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"instance": instance}))
+        .send()
+        .await
+        .expect("Failed to register an endpoint");
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let body: Value = response
+        .json()
+        .await
+        .expect("Registration must return JSON");
+    body["endpoint_id"]
+        .as_str()
+        .expect("Registration must return an endpoint id")
+        .to_string()
+}
+
+async fn wait_for_submitted(http: &Client, fixture: &HttpSourceFixture, endpoint_id: &str) {

Review Comment:
   Fixed in `1e9be7c4c` "wait for the registry on disk, not for submitted".
   
   Waiting for the file to merely change was not enough either, since a flush already in flight satisfies that without carrying the mutation. Each test now waits on a string only its own mutation writes: the new endpoint id for the registration, the revocation reason for the revoke. Checked by pointing the wait at a marker nothing writes, which panics naming the state file.



##########
.claude/skills/connector-source/SKILL.md:
##########
@@ -86,7 +107,7 @@ Match `ProducedMessages.schema` to the bytes in `messages[i].payload`:
 ### Concurrency
 
 - Runtime spawns ONE `poll()` task per source. No concurrent `poll()`.
-- Don't spawn your own long-running Tokio tasks - runtime owns lifecycle.
+- Don't spawn your own long-running Tokio tasks: the runtime owns lifecycle. The exception is a source that listens rather than polls, which has to own its listener; `http_source` is the worked example, and it shuts its tasks down in the last `close()` rather than leaving them to outlive the connector.

Review Comment:
   Fixed in `bd465a16b` "correct three skill claims about ids and side tasks".
   
   Pitfall 8 now carries the same exception the Concurrency section and the STOP list already had, including the shutdown obligation that comes with it.



##########
.claude/skills/connector-testing/SKILL.md:
##########
@@ -54,6 +54,33 @@ fn given_payload_json_should_serialize_correctly() { ... }
 
 You may **omit one part** when the test is small (`given_X_should_Y` instead of full `given_X_when_Y_should_Z`), but **stay consistent within a file**. Imperative `test_foo` / `does_bar` names are not the convention here.
 
+### Prove a test can fail, before trusting it

Review Comment:
   Fixed in `55a039d15` "name the alternative to starting fresh on invalid state".
   
   I got this one wrong the first time and should say so. I read it as the naming rule and changed that instead, then reported this thread done. The naming change was worth making, but it was not your point.
   
   Both shapes are now named. Starting fresh is right when the state is a cursor, since discarding an undecodable one costs duplicates that the at-least-once contract already permits. It is wrong when the absence of the state is a downgrade rather than a repeat, which is this connector's case: the tombstones live there, so `restore` returns `Err`. There is a worked refusal test and a line saying never to start fresh silently when the discarded state was load-bearing.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3985446867


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,

Review Comment:
   Documented in `docs(connectors): say that an unknown plugin_config key is ignored`.
   
   Both parts as you asked. The `auth_bearer_token` row now says a misspelled key reads as unset, so it opens the path rather than failing, and the configuration section carries the general rule with the reason: `deny_unknown_fields` is not available because the runtime delivers env overrides as flat top-level keys, so the silence is by design. The operational half says to grep the open log for `with NO authentication` after any configuration change.
   
   One correction to something I nearly wrote. My first draft said `management_token` was visible in the log the same way. It is not. `log_auth_posture` covers the named path and unguarded secret-path endpoints and nothing else, so a typo in `management_token` is logged nowhere. I checked rather than assumed, and the note now says what actually happens: it fails closed, so what an operator sees is `/admin/endpoints` answering 404 on the next registration.
   
   I did not add a posture line for it, since it fails closed and announces itself the first time anyone uses the API, which seemed a poor trade against another startup log line. Say if you would rather have one.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5628607486

   All twelve of round 6 are now fixed, plus one that came out of the sweep for A1. Every one has a reply on its own thread with the detail; this is the index.
   
   | Finding | Commit subject |
   | --- | --- |
   | C3 `state.rs:216` | docs(connectors): correct when an expired endpoint's secret leaves disk |
   | E1 `server.rs:760` | fix(connectors): check the bridge before the body is read, not after |
   | F1 `README.md:299` | docs(connectors): correct the batch copy count, and name the body term |
   | A1 + A2 `state.rs:69,97` | fix(connectors): frame the state file so a short read cannot fail open |
   | (found by the A1 sweep) | fix(connectors): refuse a state file that misfiles an endpoint under a new id |
   | B1 `lib.rs:887` | fix(connectors): log why open failed, since the message goes nowhere else |
   | C1 + C2 `lib.rs:987,954` | fix(connectors): let the flush backoff and the poll order see what happened |
   | E2 + E3 `server.rs:580`, `state.rs:284` | fix(connectors): give the admin listener its own limit and the cap real reach |
   | B2 `lib.rs:529` | docs(connectors): say that an unknown plugin_config key is ignored |
   | D1 `server.rs:278` | fix(connectors): publish an instance's routes when it can drain them |
   
   209 unit tests and all 13 `connectors::http` integration tests pass against a real server.
   
   Every guard was checked by deleting it and watching a test go red, and each mutant was confirmed to compile first, because one that does not looks exactly like a test that passed. Three places where a test does not prove what it might appear to are called out on their threads rather than left to look like evidence: the E3 restore test pins a decision rather than verifying a fix, the 507 log line has no test because this crate has no log capture, and D1's unit test stands in for the first poll so the integration suite is what shows the production path firing.
   
   Four corrections to my own earlier claims are on the threads: the id retargeting I first called a separate issue, the `management_token` posture I nearly documented as logged when nothing logs it, numinnex's own "before any bridge check" wording in F1 that E1 had already made false, and the backoff comment claiming a latched store always ends in the SDK stopping the source, which holds only when idle.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "codecov[bot] (via GitHub)" <gi...@apache.org>.
codecov[bot] commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5156570546

   ## [Codecov](https://app.codecov.io/gh/apache/iggy/pull/3798?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
   :white_check_mark: All modified and coverable lines are covered by tests.
   :white_check_mark: Project coverage is 75.50%. Comparing base ([`102484a`](https://app.codecov.io/gh/apache/iggy/commit/102484af2465904390e728c5f75b4df354c69d1b?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`504c603`](https://app.codecov.io/gh/apache/iggy/commit/504c6032756f0b5b4a28626e0bd44de29c04ab2d?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
   
   <details><summary>Additional details and impacted files</summary>
   
   
   
   ```diff
   @@             Coverage Diff              @@
   ##             master    #3798      +/-   ##
   ============================================
   - Coverage     75.96%   75.50%   -0.46%     
     Complexity      969      969              
   ============================================
     Files          1320     1318       -2     
     Lines        157608   157358     -250     
     Branches     130990   130933      -57     
   ============================================
   - Hits         119720   118810     -910     
   - Misses        34297    34961     +664     
   + Partials       3591     3587       -4     
   ```
   
   | [Components](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=components&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Coverage Δ | |
   |---|---|---|
   | [Rust Core](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `75.97% <ø> (ø)` | |
   | [Java SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `62.71% <ø> (ø)` | |
   | [C# SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `72.25% <ø> (ø)` | |
   | [Python SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `93.10% <ø> (ø)` | |
   | [PHP SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `84.52% <ø> (ø)` | |
   | [Node SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `88.80% <ø> (-6.44%)` | :arrow_down: |
   | [Go SDK](https://app.codecov.io/gh/apache/iggy/pull/3798/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `43.08% <ø> (ø)` | |
   [see 54 files with indirect coverage changes](https://app.codecov.io/gh/apache/iggy/pull/3798/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)
   </details>
   <details><summary> :rocket: New features to boost your workflow: </summary>
   
   - :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
   - :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
   </details>


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5593559544

   /request-review @numinnex


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984301028


##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,358 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts**, so set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, applied by the handlers rather than an extractor. Routing wins over it: an oversized POST to an unknown or revoked path answers 404 without the body being read. Must match across instances sharing a listener. **Max 67108864**; a larger value fails `open()`. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. **Max 1000000**; a larger value fails `open()`. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. **Max 100000**; a larger value fails `open()`. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie`, because forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. The endpoint keeps its slot, and its stored secret is dropped on the next restart. |
+
+An expired endpoint is not reclaimed. It keeps its `max_endpoints` slot and answers 404, and only revoking it frees the slot.
+
+Its stored secret is a different matter. The connector drops that from the registry on the next restart, because the endpoint is refused before any credential is checked and keeping it would write a credential nobody can use back to the state file on every later flush. That happens at restore only, so an endpoint that expires while the instance is running keeps its secret on disk until it restarts. Revoke it to clear the secret immediately.
+
+Env overrides reach top-level fields only, and only under the local config provider. `IGGY_CONNECTORS_SOURCE_<KEY>_PLUGIN_CONFIG_<FIELD>` sets one field of this table; the suffix is taken whole, so a nested attempt such as `..._ENDPOINTS_0_AUTH_SECRET` becomes the flat key `endpoints_0_auth_secret` and is ignored. Endpoint secrets therefore stay in TOML or go through the management API.
+
+Values are coerced before they are deserialized: `true`/`false` become booleans and anything that parses as a number becomes one. So `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` hands a JSON number to a string field and fails the whole configuration parse, with an error that does not name the field. Quote such values into non-numeric form, or set them in TOML.
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+`http_sink` calls its equivalent knob `max_payload_size_bytes`. The names differ deliberately: the sink's bounds an outgoing payload, this one bounds an accepted request.
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 405 | A known path with the wrong method | `{"error":"method not allowed"}` |
+| 429 | Bridge full | `{"error":"too many requests"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling; a named-path POST whose route changed hands while the body was still arriving; a POST whose instance left the listener mid-request; or a POST whose instance bridge has no receiver | `{"status":"unavailable"}`, `{"error":"route unavailable"}`, `{"error":"instance is closing"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+The named path splits those two cases on purpose. A path that is not configured answers 404, which is permanent and correct. A configured path whose instance stopped serving it while the body was still arriving answers 503 instead: that caller already passed bearer auth, the path does exist, and only which instance serves it changed.
+
+A 404 there would tell a conventional client the resource is gone, and it would stop retrying, so a republish window would silently drop traffic that succeeds a moment later. The secret path keeps 404 for both cases, because its caller is unauthenticated and separating "wrong id" from "busy" would leak which ids exist.
+
+The named path's 503 covers two conditions and says `route unavailable` for both: the path was withdrawn, or another instance on the same listener took it over. The caller retries either way, and the body deliberately does not say which, since that would describe the listener's topology to a sender that has no use for it.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | TCP peer address. Behind the load balancer this README recommends, that is the proxy, not the sender; forward `X-Forwarded-For` to see the original client |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 202
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only: a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |
+| ------ | --------- |
+| 400 | Empty `auth_secret`; an `auth_secret` supplied with `auth_type: none`; an `expires_at` already in the past; an `hmac_header` that is not a valid HTTP header name; a `reason`, `auth_secret`, `hmac_header` or `hmac_prefix` past its length cap |
+| 401 | Missing or wrong `management_token` |
+| 404 | Unknown endpoint, unknown `instance`, or the API is not configured |
+| 409 | Rotating a static endpoint, an endpoint whose `auth_type` is `none`, or one that has expired; or a generated id collision |
+| 415 | Missing or wrong `Content-Type` on a request that takes a body |
+| 422 | A body that parses as JSON but carries an unknown field or a wrong type |
+| 500 | The route table could not be rebuilt |
+| 503 | The owning instance closed while the request was in flight |
+| 507 | The registry is at `MAX_ENDPOINTS` with no reclaimable tombstone |
+
+Revocation writes a tombstone rather than deleting the entry. The tombstone persists, so a restart against a stale TOML file cannot resurrect an endpoint someone revoked. That rests on `open()` failing when the state file cannot be decoded, rather than falling back to the TOML: the connector reports the decode failure as `last_error` and serves nothing, instead of quietly putting revoked endpoints back on the wire.
+
+The 202 means the endpoint stopped serving *now*, in memory, and that the tombstone has been accepted but not yet persisted. It is deliberately not a 204: the change reaches the runtime only on a later `poll()`, and `submitted` flips before the state leaves the plugin, so no field on this response could honestly claim durability. Watch `GET /admin/endpoints/{id}` for it.
+
+Durability follows the same path as registration below, with one asymmetry worth knowing: losing an unsaved registration fails closed, but losing an unsaved revocation fails **open**, so the endpoint would come back after a restart.
+
+`submitted` on `GET /admin/endpoints/{id}` is not the durability check. It flips when the mutation is handed to the runtime, which happens before the runtime persists it. A save that failed shows up as `last_error` on the connector and re-arms the flush for the next poll, so treat a revocation as final only once the connector is error-free. If it cannot reach Iggy, remove the endpoint from the TOML too.
+
+Dynamic endpoints ride the SDK's `ConnectorState`, which the runtime writes after the next successful send. A management response therefore means "accepted", not "durable": if Iggy is unreachable, the endpoint is live in memory but not yet on disk, and a crash in that window loses it.
+
+`GET /admin/endpoints` reports `submitted` per endpoint. It is named that, and not `persisted`, on purpose: it says the registry was handed to the runtime, not that the write landed.
+
+It is answered per endpoint but derived instance-wide, because that is what the mechanism is. The registry is serialized and handed over whole, so no endpoint in it can be submitted while another is not, and one outstanding flush makes every endpoint unsubmitted until it lands. Since #3855 the runtime acknowledges the batch, and a failed save comes back as a NACK that re-arms the flush for the next poll, which puts the endpoints back to `submitted: false` too.
+
+That errs toward reporting not-yet-durable, which is the safe direction.
+
+## Backpressure
+
+The chain below holds end to end. It did not always: the runtime's forwarding channel is unbounded, so a slow Iggy used to show up as memory growth rather than backpressure, and #3795 proposed bounding it.
+
+What closed the gap instead was #3855. The SDK now keeps one batch in flight and will not call `poll()` again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop directly. The bridge then fills on arrival and the handlers answer 429, which is the coupling that was missing.
+
+That coupling holds only while the runtime answers inside the SDK's batch-result timeout, 30s. Past it the SDK stops waiting, NACKs, and polls again, so the bridge drains and the pressure moves into the runtime's unbounded forwarding channel instead of reaching the sender. Tracked in #3981.
+
+```text
+Iggy slow -> forwarding loop blocks -> batch stays unacknowledged -> poll() stalls
+          -> instance bridge fills -> HTTP 429 + Retry-After: 1
+```
+
+The handler never blocks on a full bridge. Waiting would hold connections open and, once the sender times out, produce a retry storm; a fast 429 tells the sender exactly what to do.
+
+| Traffic | `buffer_capacity` | Rationale |
+| ------- | ----------------- | --------- |
+| Under 100 req/s | 1000 | Small footprint |
+| 100 to 1000 req/s | 10000 (default) | Absorbs roughly ten seconds of burst |
+| Over 1000 req/s | 50000 to 100000 | Sustained bursts; tune against the buffer metrics |
+
+The bridge is bounded by message count, not bytes, so its worst case is `buffer_capacity * max_body_size_bytes`. At the defaults that is about 10 GB. Add the in-flight batch on top: at the moment of a send a batch exists as the staged copy this connector holds for replay, the SDK's serialized copy, and the runtime's decoded copy, so budget up to three times `max_batch_size * max_body_size_bytes` above the bridge. Size all of them together.

Review Comment:
   Both fixed in `docs(connectors): correct the batch copy count, and name the body term`.
   
   Four, and I checked the shadowing myself rather than take the count: `let messages = match postcard::to_allocvec(&messages)` rebinds, and Rust does not drop the shadowed value, so the polled `ProducedMessages` lives to the end of the poll arm alongside the serialized bytes. The paragraph now lists staged, polled, serialized, runtime-decoded, and says which one is easy to miss and why, since this is the second wrong count in it.
   
   The in-flight body term is in, as its own paragraph, pointing at the reverse proxy note for what bounds it.
   
   One wording change against what you wrote: I did not keep "before any bridge check", because it stopped being true two commits earlier. `server.rs:760` is fixed, so both handlers now check the bridge before the read. That check only sheds once the bridge is already full, though, so it does not bound this term at all: while the bridge has room every open request still buffers its whole body, and nothing here caps how many are open. The paragraph says it that way.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984375499


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,

Review Comment:
   Taken, including the timing argument. Fixed in `fix(connectors): frame the state file so a short read cannot fail open`.
   
   The frame is what you described: `{version, endpoint_count, endpoints}`, no field defaulted, decoded through `Deserializer::new(Cursor::new(blob))` with `position()` compared against the length. You were right that it cannot be done in the SDK helper: `position()` only exists on that flavour. `rmp-serde` moved from dev-dependencies to dependencies for it.
   
   I checked each of the three parts is actually carrying weight by deleting it and running the tests, and each one is killed by exactly one test:
   
   - arity rejects the old one-element shape, `[0x90]`, and anything shortened
   - the consumed length rejects a valid frame with bytes behind it
   - the declared count rejects a frame that is the right shape, fully consumed, and carrying a map somebody made smaller. Nothing else catches that one, which is your `[0x91,0x80]` case moved forward a format.
   
   Then I swept it rather than trusting the three repros. Real 141 byte blob holding a tombstone, every single byte position against every value, plus every prefix. 5917 of those still decode, and not one of them decodes with fewer endpoints than it was written with. Every prefix is refused. That sweep is now a test.
   
   One thing the framing does not close, and I do not think it can. Edit a byte inside an endpoint id and you get a frame that is well formed, fully consumed, and honest about its count, still carrying its tombstone but under a different id, so the original id serves again from TOML. 480 of the mutations do that. It is a fail-open, but it is an integrity property of the file rather than a decode property, so it wants a different mechanism and I did not want to invent one inside this finding. The test says so in as many words. Your call whether it is worth its own issue.
   
   I also dropped `#[serde(default)]` from the registry, but I will not claim it as load-bearing: the frame carries the map directly now, so the registry serde is off the state path and that removal is defence in depth.
   
   Deliberately not done here: bounding the decoded map by `MAX_ENDPOINTS`. That is your `state.rs:284` finding and you asked for a warn in `restore` there rather than a refusal, so putting a hard cap in the decode would contradict it.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3867623590


##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1659 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::ArcSwap;
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+pub async fn leave(instance: &Arc<SharedState>) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let remaining: Vec<Arc<SharedState>> = server
+        .state
+        .instances()
+        .into_iter()
+        .filter(|joined| joined.id != instance.id)
+        .collect();
+    let remaining_count = remaining.len();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    server
+        .state
+        .metrics
+        .forget_instance(&instance.instance_name);
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    routes: ArcSwap<RouteTable>,
+    instances: ArcSwap<Vec<Arc<SharedState>>>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            routes: ArcSwap::from_pointee(RouteTable::default()),
+            instances: ArcSwap::from_pointee(Vec::new()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        (**self.instances.load()).clone()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.instances
+            .load()
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.routes.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.secret_path_count(),
+            dropped.named_path_count(),
+            self.instances.load().len()
+        );
+        self.routes.store(Arc::new(RouteTable::default()));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let table = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.instances.store(Arc::new(instances));
+        self.routes.store(Arc::new(table));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone()),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {

Review Comment:
   Doc bug fixed. On the bypass, I tried the obvious fix and backed it out, because it bans a legitimate deployment.
   
   The obvious fix is to make the `instance_name` check global across `SERVERS` rather than per listener. I wrote that, and it failed eleven management tests. The tests were right and I was wrong: both things the name protects are per listener, not global. `ServerState::instance()` resolves a name within the listener the admin request arrived on, and each `SharedServer` owns its own `Metrics` registry, scraped through its own `/admin/metrics`. Two instances on two genuinely separate listeners, on different ports, can share a name without either being ambiguous, and a global check would refuse a config that works today.
   
   So the split itself is not the defect. Two listeners is a supported deployment; what is a defect is that an operator who *meant* one listener and mistyped `listen_addr` gets there silently.
   
   What I changed instead targets exactly that. `listen_addr` cannot be validated against the listener it selects, since it is what selects it, so the README no longer claims it is, and now explains that identical spelling is what groups instances. And since the second instance does still fail to bind, the `AddrInUse` arm now names the possibility that another instance was meant to share the listener, instead of leaving an address-in-use error pointing at a field the operator believes is shared.
   
   That leaves the case where `admin_listen_addr` differs too and both binds genuinely succeed. There the two listeners are indistinguishable from an intentional two-listener deployment, so I do not think the connector can tell them apart. If you want that closed, the honest lever is upstream: the runtime knows both instances and could reject two sources whose `listen_addr` values resolve to overlapping sockets. Say the word and I will file it.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3938512620


##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.

Review Comment:
   warning: env overrides only reach top-level fields, and only with the local config provider, so an endpoint's `auth_secret` cannot come from the environment. `..._ENDPOINTS_0_AUTH_SECRET` lands as an ignored key. say that endpoint secrets stay in toml or go through the management api.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",
+            self.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        tokio::select! {
+            // The SDK races poll() against its own shutdown watch, so blocking
+            // here until traffic arrives is what keeps an idle gateway off the
+            // CPU. crossfire documents recv() as cancellation-safe.
+            received = receiver.recv() => match received {
+                Ok(message) => {
+                    queued.push(message);
+                    while queued.len() < max_batch_size {
+                        let Ok(message) = receiver.try_recv() else {
+                            break;
+                        };
+                        queued.push(message);
+                    }
+                }
+                // Reachable only once every sender is gone. Idle rather than
+                // spin the SDK's poll loop.
+                Err(_) => tokio::time::sleep(IDLE_POLL_INTERVAL).await,
+            },
+            _ = self.shared.state_flush.notified() => {}
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            self.shared.take_dirty_state()
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free. A Nack means neither happened, so the copy has

Review Comment:
   warning: a nack does not mean neither happened. the runtime nacks after a successful send when the state save fails, after a partial commit, and on the sdk's result timeout, so this replay is at-least-once. reword here, in the readme duplicate windows and in the connector-source skill.
   
   also README.md:20-25 and `.claude/skills/connector-source/SKILL.md:67`.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());

Review Comment:
   nit: every mutation clones the whole registry, every flush clones and serializes it again, and every republish clones each endpoint into the route table. fine at hundreds of endpoints, worth a sizing note in the readme.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    let presented = request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(strip_bearer)
+        .map(SecretString::from);
+    match presented {
+        Some(presented) if secrets_match(&presented, expected) => None,
+        _ => Some(error_response(StatusCode::UNAUTHORIZED, "unauthorized")),
+    }
+}
+
+fn is_usable(secret: &Option<SecretString>) -> bool {
+    secret
+        .as_ref()
+        .is_some_and(|secret| !secret.expose_secret().is_empty())
+}
+
+fn owner_of(state: &ServerState, endpoint_id: &str) -> Option<Arc<SharedState>> {
+    state
+        .instances()
+        .into_iter()
+        .find(|instance| instance.registry().endpoint(endpoint_id).is_some())
+}
+
+/// Whether the instance a handler resolved earlier is still the one joined
+/// under that name. A handler awaits between resolving and mutating, and an
+/// instance can close in between - the mutation would then land on a registry
+/// nobody polls and the caller would be told it succeeded.
+fn still_joined(state: &ServerState, instance: &Arc<SharedState>) -> bool {
+    state
+        .instance(&instance.instance_name)
+        .is_some_and(|current| Arc::ptr_eq(&current, instance))
+}
+
+/// Projects the mutated registry into the shared route table.
+///
+/// A failure here leaves the registry ahead of the routes, so it answers 500
+/// rather than pretending the endpoint is live.
+async fn republish(state: &ServerState) -> Option<Response> {
+    let Err(error) = refresh_routes(&state.listen_addr).await else {
+        return None;
+    };
+    warn!(
+        "Failed to republish {CONNECTOR_NAME} routes on {}. {error}",
+        state.listen_addr
+    );
+    Some(error_response(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        "route update failed",
+    ))
+}
+
+/// Republish for a mutation that takes access AWAY. If the table cannot be
+/// rebuilt, the old one is still serving the endpoint the operator just
+/// revoked or re-keyed, so serve nothing rather than a credential they
+/// believe is dead.
+async fn republish_or_close(state: &ServerState) -> Option<Response> {
+    let failure = republish(state).await?;
+    state.serve_nothing();
+    Some(failure)
+}
+
+fn summary_response(instance: &Arc<SharedState>, endpoint_id: &str) -> Response {
+    let registry = instance.registry();
+    match registry.endpoint(endpoint_id) {
+        Some(endpoint) => Json(EndpointSummary::new(instance, endpoint)).into_response(),
+        None => error_response(StatusCode::NOT_FOUND, "not found"),
+    }
+}
+
+fn generate_endpoint_id() -> EndpointId {
+    let bytes: [u8; ENDPOINT_ID_BYTES] = rand::rng().random();
+    hex::encode(bytes)
+        .parse()
+        .expect("hex of 16 bytes is 32 lowercase hex characters")
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env

Review Comment:
   nit: the same two-line comment sits on all three request structs. keep one.
   
   also at lines 431, 439.



##########
core/connectors/sources/http_source/src/types.rs:
##########
@@ -0,0 +1,268 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::ProducedMessage;
+use serde::{Deserialize, Serialize};
+use std::borrow::Borrow;
+use std::collections::BTreeMap;
+use std::fmt::{self, Display, Formatter};
+use std::str::FromStr;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Iggy `HeaderValue` rejects values above this size, and forwarded HTTP
+/// header values (e.g. `User-Agent`) routinely exceed it.
+pub const MAX_HEADER_VALUE_BYTES: usize = 255;
+
+/// Validated secret-path endpoint identifier: exactly 32 lowercase hex
+/// characters, giving the URL itself 128 bits of entropy.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct EndpointId(String);
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EndpointIdError {
+    InvalidLength(usize),
+    InvalidCharacter(char),
+}
+
+impl EndpointId {
+    pub const LENGTH: usize = 32;
+    const LOG_PREFIX_LENGTH: usize = 8;
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// A correlation handle for logs. The full id is the credential for a
+    /// secret-path endpoint, so it must never reach a log line.
+    pub fn log_prefix(&self) -> String {
+        Self::log_prefix_of(&self.0)
+    }
+
+    pub fn log_prefix_of(endpoint_id: &str) -> String {
+        // `chars`, not a byte slice: ids are validated hex so the boundary is
+        // never split today, but this also runs on rejected input from
+        // `EndpointIdError`, and a byte index into UTF-8 would panic there.
+        let prefix: String = endpoint_id.chars().take(Self::LOG_PREFIX_LENGTH).collect();
+        format!("{prefix}...")
+    }
+}
+
+impl FromStr for EndpointId {
+    type Err = EndpointIdError;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        if value.len() != Self::LENGTH {
+            return Err(EndpointIdError::InvalidLength(value.len()));
+        }
+        if let Some(invalid) = value
+            .chars()
+            .find(|character| !matches!(character, '0'..='9' | 'a'..='f'))
+        {
+            return Err(EndpointIdError::InvalidCharacter(invalid));
+        }
+        Ok(Self(value.to_string()))
+    }
+}
+
+impl TryFrom<String> for EndpointId {
+    type Error = EndpointIdError;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        value.parse()
+    }
+}
+
+impl From<EndpointId> for String {
+    fn from(endpoint_id: EndpointId) -> Self {
+        endpoint_id.0
+    }
+}
+
+/// Lets `HashMap<EndpointId, _>` be probed with the raw path segment, so
+/// request routing never allocates. Sound because the derived `Hash` on a
+/// single-field newtype hashes exactly as the inner `String`, which in turn
+/// hashes as `str`.
+impl Borrow<str> for EndpointId {
+    fn borrow(&self) -> &str {
+        &self.0
+    }
+}
+
+impl Display for EndpointId {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}", self.0)
+    }
+}
+
+impl Display for EndpointIdError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidLength(length) => write!(
+                formatter,
+                "endpoint_id must be exactly {} characters, got {length}",
+                EndpointId::LENGTH
+            ),
+            Self::InvalidCharacter(character) => write!(
+                formatter,
+                "endpoint_id must be lowercase hex, found: {character}"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for EndpointIdError {}
+
+/// Message accepted by an HTTP handler, queued for `poll()` to drain.
+///
+/// `Clone` exists so a batch can be held aside until the runtime acknowledges
+/// it: the bridge drain in `poll()` is destructive, so a NACKed batch has no
+/// other copy to fall back on.
+#[derive(Debug, Clone)]
+pub struct QueuedMessage {
+    /// Raw HTTP request body bytes, exactly as received.
+    pub payload: Vec<u8>,
+    /// Already filtered, clamped, and converted by the handler, so draining
+    /// the queue cannot fail on a malformed header.
+    pub headers: Option<BTreeMap<HeaderKey, HeaderValue>>,
+}
+
+impl From<QueuedMessage> for ProducedMessage {
+    fn from(message: QueuedMessage) -> Self {
+        ProducedMessage {
+            // Webhook bodies carry no identifier this connector can trust as a
+            // dedupe key, and `timestamp` / `checksum` are Iggy's to fill.
+            id: None,

Review Comment:
   warning: `id: None` becomes wire id 0 on every message, so a replayed batch has no stable id to dedupe on. mint a random `u128` in `enqueue`, keep it on `QueuedMessage`, and set it here.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,602 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            endpoint.submitted = true;
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked
+                && endpoint.auth_type.hmac_algorithm().is_some()
+                && HeaderName::from_str(&endpoint.hmac_header).is_err()
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id} with hmac_header '{}', which is not a valid HTTP header name; every signed request to it will be rejected until it is re-registered",
+                    endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {

Review Comment:
   critical: the vacant arm re-inserts any persisted active entry without checking `origin`, and the state file carries static endpoints with their secrets. delete a static endpoint from toml and restart: it comes back serving, and `rotate_secret` then refuses it as static. skip persisted static entries that toml no longer declares, and add a restore test for that case.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,

Review Comment:
   warning: the `Bytes` extractor buffers the whole body before `lookup_secret_path` runs, so unknown or revoked ids cost a full read per 404 on the public listener. take `Request`, check route and bearer first, then `to_bytes` only for active endpoints, as the named path does.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {

Review Comment:
   warning: `join()` rejects while a sibling's `leave()` is still draining, so two concurrent `/restart` calls on instances sharing a listener leave one of them stopped with `last_error: None`. drop the `SERVERS` guard, wait on a `Notify` fired after the map removal, then retry the lookup.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",
+            self.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        tokio::select! {
+            // The SDK races poll() against its own shutdown watch, so blocking
+            // here until traffic arrives is what keeps an idle gateway off the
+            // CPU. crossfire documents recv() as cancellation-safe.
+            received = receiver.recv() => match received {

Review Comment:
   nit: unbiased `select!` means a pending flush waits a coin-flip number of polls, mean two. `biased;` with the `notified()` arm first makes it ride the next poll, but guard it so two state-only batches never run back to back or a mutation flood starves `recv()`.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()

Review Comment:
   warning: 204 goes out before the tombstone reaches the runtime, and the `submitted` flag flips before the state leaves the plugin, so waiting on it would not help. answer 202 and point at `GET /admin/endpoints/{id}`, or add an ack generation counter to wait on.
   
   also at line 189.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,602 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            endpoint.submitted = true;
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked
+                && endpoint.auth_type.hmac_algorithm().is_some()
+                && HeaderName::from_str(&endpoint.hmac_header).is_err()
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id} with hmac_header '{}', which is not a valid HTTP header name; every signed request to it will be rejected until it is re-registered",
+                    endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"
+        );
+
+        Ok(EndpointRegistry { endpoints })
+    }
+
+    pub fn endpoints(&self) -> impl Iterator<Item = &Endpoint> {
+        self.endpoints.values()
+    }
+
+    pub fn endpoint(&self, endpoint_id: &str) -> Option<&Endpoint> {
+        self.endpoints.get(endpoint_id)
+    }
+
+    pub fn endpoint_mut(&mut self, endpoint_id: &str) -> Option<&mut Endpoint> {
+        self.endpoints.get_mut(endpoint_id)
+    }
+
+    /// Registers a new endpoint, refusing to overwrite an existing one so a
+    /// generated-id collision can never silently retarget live traffic.
+    pub fn insert(&mut self, endpoint: Endpoint) -> bool {

Review Comment:
   warning: nothing caps the registry, tombstones are never evicted, and every flush serializes and rewrites the whole thing. an authenticated caller can grow the state file without bound. add a `MAX_ENDPOINTS` ceiling here and a tombstone purge route.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,

Review Comment:
   simplification: duplicates `shared.id`, every use is a log line. drop it.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {

Review Comment:
   warning: rotate only checks `is_active()`. with `auth_type: none` it answers 200 and persists a secret `authorize` never reads, and for an expired endpoint it answers 200 for a path that 404s. reject both.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {

Review Comment:
   warning: `still_joined` only checks membership, so after the sdk stops the poll task these handlers keep answering 201/204 for mutations nothing will ever persist, and the admin listener has no liveness signal to notice. expose `poll_is_live` on `/admin/health` and `warn!` here when it is false.



##########
core/integration/tests/connectors/fixtures/http/source.rs:
##########
@@ -0,0 +1,116 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use async_trait::async_trait;
+use integration::harness::{TestBinaryError, TestFixture};
+use ring::hmac;
+use std::collections::HashMap;
+use std::net::TcpListener;
+
+/// Both instances in `tests/connectors/http/source_config` share one listener,
+/// so they must be handed the same pair of addresses.
+const ENV_GITHUB_LISTEN_ADDR: &str = "IGGY_CONNECTORS_SOURCE_HTTP_GITHUB_PLUGIN_CONFIG_LISTEN_ADDR";
+const ENV_GITHUB_ADMIN_LISTEN_ADDR: &str =
+    "IGGY_CONNECTORS_SOURCE_HTTP_GITHUB_PLUGIN_CONFIG_ADMIN_LISTEN_ADDR";
+const ENV_PARTNER_LISTEN_ADDR: &str =
+    "IGGY_CONNECTORS_SOURCE_HTTP_PARTNER_PLUGIN_CONFIG_LISTEN_ADDR";
+const ENV_PARTNER_ADMIN_LISTEN_ADDR: &str =
+    "IGGY_CONNECTORS_SOURCE_HTTP_PARTNER_PLUGIN_CONFIG_ADMIN_LISTEN_ADDR";
+
+/// Static endpoints declared in those configurations.
+pub const GITHUB_ENDPOINT_ID: &str = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d";
+pub const GITHUB_HMAC_SECRET: &str = "whsec_github_test";
+pub const GITHUB_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const PARTNER_ENDPOINT_ID: &str = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81";
+pub const PARTNER_BEARER_TOKEN: &str = "partner-token-test";
+pub const MANAGEMENT_TOKEN: &str = "mgmt-token-test";
+pub const GITHUB_INSTANCE: &str = "http_github";
+pub const PARTNER_INSTANCE: &str = "http_partner";
+
+/// Boots the webhook gateway on ports nobody else in this test run holds.
+///
+/// Unlike the container-backed fixtures there is no external system here: the
+/// connector is itself the HTTP server, and the test's own client is the
+/// webhook sender.
+pub struct HttpSourceFixture {
+    public_addr: String,
+    admin_addr: String,
+}
+
+impl HttpSourceFixture {
+    pub fn public_url(&self) -> String {
+        format!("http://{}", self.public_addr)
+    }
+
+    pub fn admin_url(&self) -> String {
+        format!("http://{}", self.admin_addr)
+    }
+
+    pub fn webhook_url(&self, endpoint_id: &str) -> String {
+        format!("{}/e/{endpoint_id}", self.public_url())
+    }
+
+    /// The named path, which is the other half of the routing surface and the
+    /// one a sender reaches without a per-endpoint secret.
+    pub fn named_url(&self, topic_path: &str) -> String {
+        format!("{}/topics/{topic_path}", self.public_url())
+    }
+
+    /// GitHub-style `sha256=<hex>` over the exact bytes that will be sent.
+    pub fn github_signature(&self, body: &[u8]) -> String {
+        let key = hmac::Key::new(hmac::HMAC_SHA256, GITHUB_HMAC_SECRET.as_bytes());
+        format!("sha256={}", hex::encode(hmac::sign(&key, body).as_ref()))
+    }
+
+    /// Reserves an ephemeral port and releases it so the connector can bind it.
+    /// A fixed port would collide as soon as two of these tests run at once.
+    fn reserve_port() -> Result<u16, TestBinaryError> {
+        let listener = TcpListener::bind("127.0.0.1:0").map_err(TestBinaryError::Io)?;

Review Comment:
   warning: bind, read the port, drop the listener - anyone binding in between takes the port, and tests run in parallel next to `iggy-server`. hold both listeners until both ports are chosen, or retry on `AddrInUse`. `free_port` in `lib.rs:882` has the same shape.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,602 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            endpoint.submitted = true;
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked
+                && endpoint.auth_type.hmac_algorithm().is_some()
+                && HeaderName::from_str(&endpoint.hmac_header).is_err()
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id} with hmac_header '{}', which is not a valid HTTP header name; every signed request to it will be rejected until it is re-registered",
+                    endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"
+        );
+
+        Ok(EndpointRegistry { endpoints })
+    }
+
+    pub fn endpoints(&self) -> impl Iterator<Item = &Endpoint> {
+        self.endpoints.values()
+    }
+
+    pub fn endpoint(&self, endpoint_id: &str) -> Option<&Endpoint> {
+        self.endpoints.get(endpoint_id)
+    }
+
+    pub fn endpoint_mut(&mut self, endpoint_id: &str) -> Option<&mut Endpoint> {
+        self.endpoints.get_mut(endpoint_id)
+    }
+
+    /// Registers a new endpoint, refusing to overwrite an existing one so a
+    /// generated-id collision can never silently retarget live traffic.
+    pub fn insert(&mut self, endpoint: Endpoint) -> bool {
+        match self.endpoints.entry(endpoint.endpoint_id.clone()) {
+            Entry::Occupied(_) => false,
+            Entry::Vacant(vacant) => {
+                vacant.insert(endpoint);
+                true
+            }
+        }
+    }
+
+    /// Drops an endpoint outright, as opposed to tombstoning it. Only for
+    /// undoing a registration that never became reachable; a live endpoint is
+    /// always revoked instead, so the tombstone survives a restart.
+    pub fn remove(&mut self, endpoint_id: &str) -> bool {
+        self.endpoints.remove(endpoint_id).is_some()
+    }
+
+    pub fn revoke(&mut self, endpoint_id: &str, reason: String, revoked_at: u64) -> bool {
+        let Some(endpoint) = self.endpoints.get_mut(endpoint_id) else {
+            return false;
+        };
+        if !endpoint.is_active() {
+            return false;
+        }
+        endpoint.revoke(reason, revoked_at);
+        true
+    }
+
+    /// Flags the whole registry as handed to the runtime for persistence.
+    ///
+    /// Set when the registry is handed to the runtime, which is why the flag
+    /// is `submitted` rather than `persisted`. The runtime does acknowledge
+    /// the batch, and a failed save comes back as a NACK that re-arms the
+    /// flush without clearing this, so between a failed save and the retry
+    /// that succeeds the flag over-reports. Nothing here may assume the save
+    /// landed, and `HttpSource::on_nack`'s re-arm is what makes the retry
+    /// happen: it is load-bearing, not defensive.
+    pub fn mark_submitted(&mut self) {
+        for endpoint in self.endpoints.values_mut() {
+            endpoint.submitted = true;
+        }
+    }
+
+    /// Endpoints that would accept a request right now: neither revoked nor
+    /// past their expiry. An expired endpoint is still `Active` in lifecycle
+    /// terms but answers 404, so counting it as serving would mislead.
+    pub fn serving_count(&self, now_seconds: u64) -> usize {
+        self.endpoints
+            .values()
+            .filter(|endpoint| endpoint.is_serving(now_seconds))
+            .count()
+    }
+
+    pub fn serving_count_by_origin(&self, origin: EndpointOrigin, now_seconds: u64) -> usize {
+        self.endpoints
+            .values()
+            .filter(|endpoint| endpoint.is_serving(now_seconds) && endpoint.origin == origin)
+            .count()
+    }
+
+    /// Serving endpoints whose URL is the only thing guarding them.
+    pub fn serving_count_without_auth(&self, now_seconds: u64) -> usize {
+        self.endpoints
+            .values()
+            .filter(|endpoint| {
+                endpoint.is_serving(now_seconds) && endpoint.auth_type == EndpointAuthType::None
+            })
+            .count()
+    }
+
+    pub fn expired_count(&self, now_seconds: u64) -> usize {
+        self.endpoints
+            .values()
+            .filter(|endpoint| endpoint.is_active() && endpoint.is_expired(now_seconds))
+            .count()
+    }
+
+    pub fn revoked_count(&self) -> usize {
+        self.endpoints
+            .values()
+            .filter(|endpoint| !endpoint.is_active())
+            .count()
+    }
+
+    /// Whether every endpoint has been handed to the runtime, which is what
+    /// the admin listener reports as `state_submitted`.
+    pub fn all_submitted(&self) -> bool {
+        self.endpoints.values().all(|endpoint| endpoint.submitted)
+    }
+
+    pub fn to_connector_state(&self, connector_id: u32) -> Option<ConnectorState> {
+        ConnectorState::serialize(self, CONNECTOR_NAME, connector_id)
+    }
+}
+
+/// Writes an endpoint secret in the clear, for `ConnectorState` only.
+///
+/// A local helper rather than the shared
+/// [`iggy_common::serde_secret::serialize_optional_secret`] so that the one
+/// place in this crate that deliberately writes a secret is greppable and
+/// cannot be reached by accident: `HttpSourceConfig` does not implement
+/// `Serialize` at all, precisely so a credential cannot leak that way.
+pub fn serialize_secret_to_state<S>(

Review Comment:
   simplification: this is `iggy_common::serde_secret::serialize_optional_secret` line for line. point `serialize_with` at that and delete this.



##########
core/connectors/sources/http_source/src/auth.rs:
##########
@@ -0,0 +1,267 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::sync::LazyLock;
+
+/// HMAC algorithms accepted for signature validation. SHA-256 covers GitHub,
+/// Stripe, and most modern providers; SHA-1 exists only for legacy senders.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum HmacAlgorithm {
+    HmacSha256,
+    HmacSha1,
+}
+
+impl HmacAlgorithm {
+    fn ring_algorithm(self) -> hmac::Algorithm {
+        match self {
+            Self::HmacSha256 => hmac::HMAC_SHA256,
+            Self::HmacSha1 => hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY,
+        }
+    }
+}
+
+/// Validates `Authorization: Bearer <token>` in constant time.
+pub fn validate_bearer(authorization_header: Option<&str>, expected_token: &SecretString) -> bool {
+    let Some(header_value) = authorization_header else {
+        return false;
+    };
+    let Some(presented_token) = strip_bearer(header_value) else {
+        return false;
+    };
+    constant_time_eq(
+        presented_token.as_bytes(),
+        expected_token.expose_secret().as_bytes(),
+    )
+}
+
+/// Splits `Bearer <token>`. RFC 7235 makes the scheme case-insensitive, so a
+/// sender using `bearer` is legitimate and must not be turned away.
+pub fn strip_bearer(header_value: &str) -> Option<&str> {
+    let (scheme, token) = header_value.split_once(' ')?;
+    // RFC 9110's grammar is `auth-scheme [ 1*SP token68 ]`, so more than one
+    // space is legal and the extra would otherwise fail the compare.
+    scheme
+        .eq_ignore_ascii_case("Bearer")
+        .then(|| token.trim_start_matches(' '))
+}
+
+/// Compares two secrets without leaking their contents through timing.
+pub fn secrets_match(left: &SecretString, right: &SecretString) -> bool {
+    constant_time_eq(
+        left.expose_secret().as_bytes(),
+        right.expose_secret().as_bytes(),
+    )
+}
+
+// ring deprecated its direct comparison helper; `hmac::verify` compares
+// tags in constant time, so equal inputs iff the tag over one verifies
+// against the other.
+/// Built once. The key material is empty and fixed, so rebuilding it per
+/// comparison only repeated the block-size padding work on the token path.
+static COMPARE_KEY: LazyLock<hmac::Key> = LazyLock::new(|| hmac::Key::new(hmac::HMAC_SHA256, &[]));
+
+fn constant_time_eq(left: &[u8], right: &[u8]) -> bool {
+    // Signing one side and verifying the other compares tags of a fixed
+    // length, so neither the result nor the timing depends on where the inputs
+    // first differ. Total time is still proportional to their length, since
+    // each HMAC runs one compression per block, so a presented token's length
+    // remains observable. That is the known caveat of this construction and is
+    // acceptable here: length alone does not narrow a secret's content.
+    let left_tag = hmac::sign(&COMPARE_KEY, left);
+    hmac::verify(&COMPARE_KEY, right, left_tag.as_ref()).is_ok()
+}
+
+/// Validates an HMAC signature over the raw request body bytes, never a
+/// re-serialized form (whitespace or key-order changes would break the hash).
+/// `ring::hmac::verify` compares in constant time.
+pub fn validate_hmac(
+    body: &[u8],
+    signature_header: Option<&str>,
+    signature_prefix: &str,
+    secret: &SecretString,
+    algorithm: HmacAlgorithm,
+) -> bool {
+    let Some(header_value) = signature_header else {
+        return false;
+    };
+    let Some(signature_hex) = header_value.strip_prefix(signature_prefix) else {
+        return false;
+    };
+    let Ok(expected_signature) = hex::decode(signature_hex) else {
+        return false;
+    };
+    let key = hmac::Key::new(

Review Comment:
   nit: the hmac key is rebuilt and the tag hex-decoded on every request while `COMPARE_KEY` is cached. build the key once per endpoint in `RouteTable::build` and decode the tag into a stack array. note `hmac::Key` is not `Debug`.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",
+            self.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        tokio::select! {
+            // The SDK races poll() against its own shutdown watch, so blocking
+            // here until traffic arrives is what keeps an idle gateway off the
+            // CPU. crossfire documents recv() as cancellation-safe.
+            received = receiver.recv() => match received {
+                Ok(message) => {
+                    queued.push(message);
+                    while queued.len() < max_batch_size {
+                        let Ok(message) = receiver.try_recv() else {
+                            break;
+                        };
+                        queued.push(message);
+                    }
+                }
+                // Reachable only once every sender is gone. Idle rather than
+                // spin the SDK's poll loop.
+                Err(_) => tokio::time::sleep(IDLE_POLL_INTERVAL).await,
+            },
+            _ = self.shared.state_flush.notified() => {}
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            self.shared.take_dirty_state()
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free. A Nack means neither happened, so the copy has
+    /// to outlive it for the next `poll()` to replay.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();
+                Ok(())
+            }
+            source::SourceBatchResult::Nack => self.on_nack(),
+        }
+    }
+
+    async fn close(&mut self) -> Result<(), Error> {

Review Comment:
   warning: `close()` never looks at `has_pending_state()`. a revoke issued after the last poll before a stop is dropped silently and the endpoint is live again after restart. at least `warn!` with the unsubmitted count.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),
+        headers,
+    };
+    if let Err(error) = instance.sender.try_send(message) {
+        // A disconnected bridge is not a full one. It cannot happen while the
+        // route table holds an `Arc` to this `SharedState`, but reporting it as
+        // backpressure would tell a sender to retry into a channel that no
+        // longer has a receiver, and would file the loss under the wrong metric.
+        if matches!(error, crossfire::TrySendError::Disconnected(_)) {
+            metrics.record_rejected_disconnected(&instance.instance_name);
+            error!(
+                "Rejected a request for {CONNECTOR_NAME} connector ID: {}, its bridge has no receiver",
+                instance.id
+            );
+            return (
+                StatusCode::SERVICE_UNAVAILABLE,
+                Json(ErrorResponse {
+                    error: "service unavailable",
+                }),
+            )
+                .into_response();
+        }
+        metrics.record_rejected_full(&instance.instance_name);
+        debug!(
+            "Rejected a request for {CONNECTOR_NAME} connector ID: {}, bridge is full at {} messages",
+            instance.id, instance.config.buffer_capacity
+        );
+        return (
+            StatusCode::TOO_MANY_REQUESTS,
+            [(header::RETRY_AFTER, "1")],
+            Json(ErrorResponse {
+                error: "service temporarily unavailable",
+            }),
+        )
+            .into_response();
+    }
+    // Only now: a rejected request produced no message, so its header losses
+    // would otherwise be counted against messages that never existed.
+    metrics.record_headers(&instance.instance_name, clamped, dropped);
+    Json(StatusResponse { status: "queued" }).into_response()
+}
+
+fn authorize(endpoint: &Endpoint, request_headers: &HeaderMap, body: &[u8]) -> bool {
+    match endpoint.auth_type {
+        EndpointAuthType::None => true,
+        EndpointAuthType::Bearer => endpoint
+            .auth_secret
+            .as_ref()
+            .is_some_and(|secret| validate_bearer(bearer_header(request_headers), secret)),
+        EndpointAuthType::HmacSha256 | EndpointAuthType::HmacSha1 => {
+            let (Some(secret), Some(algorithm)) = (
+                endpoint.auth_secret.as_ref(),
+                endpoint.auth_type.hmac_algorithm(),
+            ) else {
+                return false;
+            };
+            validate_hmac(
+                body,
+                header_str(request_headers, &endpoint.hmac_header),
+                &endpoint.hmac_prefix,
+                secret,
+                algorithm,
+            )
+        }
+    }
+}
+
+/// Builds the Iggy headers an accepted request rides with.
+///
+/// Values Iggy would reject are dropped rather than failing the message: a
+/// webhook body is worth more than a `User-Agent`.
+///
+/// Returns the headers to attach plus the number of forwarded values that were
+/// truncated and dropped. The counts are returned rather than recorded here so
+/// a request that is ultimately rejected does not report losses for a message
+/// that was never produced.
+fn message_headers(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+) -> (Option<BTreeMap<HeaderKey, HeaderValue>>, u64, u64) {
+    let mut headers = BTreeMap::new();
+    let mut dropped = 0;
+    let mut clamped = 0;
+    if instance.config.include_http_metadata {
+        insert_header(&mut headers, &INSTANCE_HEADER_KEY, &instance.instance_name);
+        insert_header(
+            &mut headers,
+            &REMOTE_ADDR_HEADER_KEY,
+            &remote_addr.ip().to_string(),
+        );
+        if let Some(received_at) = received_at_micros() {
+            insert_header(&mut headers, &RECEIVED_AT_HEADER_KEY, &received_at);
+        }
+    }
+
+    for (name, key) in &instance.forward_headers {
+        let Some(present) = request_headers.get(name) else {
+            continue;
+        };
+        // Present but unrepresentable is a loss; absent is not. `to_str`
+        // rejects any byte outside visible ASCII, which a UTF-8 User-Agent
+        // routinely carries.
+        let Ok(raw) = present.to_str() else {
+            dropped += 1;
+            continue;
+        };
+        let Some(value) = clamp_header_value(raw) else {
+            dropped += 1;
+            continue;
+        };
+        if value.len() < raw.len() {
+            clamped += 1;
+        }
+        match HeaderValue::from_str(value) {
+            Ok(value) => {
+                headers.insert(key.clone(), value);

Review Comment:
   warning: this runs after the metadata inserts into the same map, so a `forward_headers` entry named `iggy_http_remote_addr` (or the other two reserved keys) lets the sender overwrite the trusted value. reject the reserved names in `validate()`.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"

Review Comment:
   nit: `bind()` also serves `admin_listen_addr`, so a collision on the admin port blames the wrong field. pass the field name in.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds

Review Comment:
   nit: stale doc, `poll()` uses `Vec::new()` now. keep the const, it still bounds the drain loop.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();

Review Comment:
   warning: a state-only nack re-arms and re-posts the permit at once, so with the runtime's state store latched one idle mutation burns through the sdk's nack budget and the poll task stops without `close()`. bound the re-post with a delay or attempt cap. do not just drop the `notify_one`, an idle gateway then has no wakeup.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),
+        headers,
+    };
+    if let Err(error) = instance.sender.try_send(message) {
+        // A disconnected bridge is not a full one. It cannot happen while the
+        // route table holds an `Arc` to this `SharedState`, but reporting it as
+        // backpressure would tell a sender to retry into a channel that no
+        // longer has a receiver, and would file the loss under the wrong metric.
+        if matches!(error, crossfire::TrySendError::Disconnected(_)) {
+            metrics.record_rejected_disconnected(&instance.instance_name);
+            error!(
+                "Rejected a request for {CONNECTOR_NAME} connector ID: {}, its bridge has no receiver",
+                instance.id
+            );
+            return (
+                StatusCode::SERVICE_UNAVAILABLE,
+                Json(ErrorResponse {
+                    error: "service unavailable",
+                }),
+            )
+                .into_response();
+        }
+        metrics.record_rejected_full(&instance.instance_name);
+        debug!(
+            "Rejected a request for {CONNECTOR_NAME} connector ID: {}, bridge is full at {} messages",
+            instance.id, instance.config.buffer_capacity
+        );
+        return (
+            StatusCode::TOO_MANY_REQUESTS,
+            [(header::RETRY_AFTER, "1")],
+            Json(ErrorResponse {
+                error: "service temporarily unavailable",
+            }),
+        )
+            .into_response();
+    }
+    // Only now: a rejected request produced no message, so its header losses
+    // would otherwise be counted against messages that never existed.
+    metrics.record_headers(&instance.instance_name, clamped, dropped);
+    Json(StatusResponse { status: "queued" }).into_response()
+}
+
+fn authorize(endpoint: &Endpoint, request_headers: &HeaderMap, body: &[u8]) -> bool {
+    match endpoint.auth_type {
+        EndpointAuthType::None => true,
+        EndpointAuthType::Bearer => endpoint
+            .auth_secret
+            .as_ref()
+            .is_some_and(|secret| validate_bearer(bearer_header(request_headers), secret)),
+        EndpointAuthType::HmacSha256 | EndpointAuthType::HmacSha1 => {
+            let (Some(secret), Some(algorithm)) = (
+                endpoint.auth_secret.as_ref(),
+                endpoint.auth_type.hmac_algorithm(),
+            ) else {
+                return false;
+            };
+            validate_hmac(
+                body,
+                header_str(request_headers, &endpoint.hmac_header),
+                &endpoint.hmac_prefix,
+                secret,
+                algorithm,
+            )
+        }
+    }
+}
+
+/// Builds the Iggy headers an accepted request rides with.
+///
+/// Values Iggy would reject are dropped rather than failing the message: a
+/// webhook body is worth more than a `User-Agent`.
+///
+/// Returns the headers to attach plus the number of forwarded values that were
+/// truncated and dropped. The counts are returned rather than recorded here so
+/// a request that is ultimately rejected does not report losses for a message
+/// that was never produced.
+fn message_headers(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+) -> (Option<BTreeMap<HeaderKey, HeaderValue>>, u64, u64) {
+    let mut headers = BTreeMap::new();
+    let mut dropped = 0;
+    let mut clamped = 0;
+    if instance.config.include_http_metadata {
+        insert_header(&mut headers, &INSTANCE_HEADER_KEY, &instance.instance_name);
+        insert_header(
+            &mut headers,
+            &REMOTE_ADDR_HEADER_KEY,
+            &remote_addr.ip().to_string(),
+        );
+        if let Some(received_at) = received_at_micros() {
+            insert_header(&mut headers, &RECEIVED_AT_HEADER_KEY, &received_at);
+        }
+    }
+
+    for (name, key) in &instance.forward_headers {
+        let Some(present) = request_headers.get(name) else {
+            continue;
+        };
+        // Present but unrepresentable is a loss; absent is not. `to_str`
+        // rejects any byte outside visible ASCII, which a UTF-8 User-Agent
+        // routinely carries.
+        let Ok(raw) = present.to_str() else {
+            dropped += 1;
+            continue;
+        };
+        let Some(value) = clamp_header_value(raw) else {
+            dropped += 1;
+            continue;
+        };
+        if value.len() < raw.len() {
+            clamped += 1;
+        }
+        match HeaderValue::from_str(value) {
+            Ok(value) => {
+                headers.insert(key.clone(), value);
+            }
+            Err(_) => dropped += 1,
+        }
+    }
+    ((!headers.is_empty()).then_some(headers), clamped, dropped)
+}
+
+/// The three metadata keys, parsed once. They are compile-time constants, so
+/// re-parsing them per request repeated validation that can only ever succeed,
+/// the same reason `forward_headers` is resolved at construction.
+static INSTANCE_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(INSTANCE_HEADER).ok());
+static REMOTE_ADDR_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(REMOTE_ADDR_HEADER).ok());
+static RECEIVED_AT_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(RECEIVED_AT_HEADER).ok());
+
+fn insert_header(
+    headers: &mut BTreeMap<HeaderKey, HeaderValue>,
+    key: &Option<HeaderKey>,
+    value: &str,
+) {
+    let (Some(key), Ok(value)) = (key.as_ref(), HeaderValue::from_str(value)) else {
+        return;
+    };
+    headers.insert(key.clone(), value);
+}
+
+/// `None` when the clock predates the epoch, which is the only way this fails.
+///
+/// Defaulting to 0 would stamp every message with the epoch, and the header
+/// exists so a consumer can measure queue latency, so a plausible wrong value
+/// is worse than an absent one. `unix_now_seconds` saturates instead because
+/// its callers gate on expiry, where failing closed is the safe direction.
+fn received_at_micros() -> Option<String> {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .ok()
+        .map(|elapsed| elapsed.as_micros().to_string())
+}
+
+fn bearer_header(request_headers: &HeaderMap) -> Option<&str> {
+    request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+}
+
+fn header_str<'a>(request_headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+    request_headers
+        .get(name)
+        .and_then(|value| value.to_str().ok())
+}
+
+/// `to_bytes` reports the cap and a truncated stream through the same error, so
+/// the status mirrors what the `Bytes` extractor would have returned: a body
+/// that ran past the limit is 413, anything else is a 400.
+fn oversized_body_response(error: &axum::Error) -> Response {
+    let too_large = error
+        .to_string()

Review Comment:
   nit: 413 vs 400 rides on the error's display text. downcast to `LengthLimitError` instead, or at least pin the substring in a unit test.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),

Review Comment:
   nit: headers and the body copy are built before `try_send`, so a 429 pays for a message it throws away. check `sender.is_full()` first and keep `try_send` as the real gate.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still

Review Comment:
   nit: the read-back does not prevent the leak this comment describes, on the failure branch the departed instance is still in `instances()` either way. the real reason `publish(remaining)` is safe is that it is a subset of a table that already built.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On `/e/{id}` the `Bytes` extractor enforces it and the body is read before authentication, which HMAC over the raw body requires. On the named path the bearer token is checked first and the cap is applied by hand afterwards, so an unauthenticated caller never makes the process buffer. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie` — forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"service temporarily unavailable"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | Peer IP address |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 204
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only — a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |
+| ------ | --------- |
+| 400 | Empty `auth_secret`, an `expires_at` already in the past, or an `hmac_header` that is not a valid HTTP header name |
+| 401 | Missing or wrong `management_token` |
+| 404 | Unknown endpoint, unknown `instance`, or the API is not configured |
+| 409 | Rotating a static endpoint, or a generated id collision |
+| 500 | The route table could not be rebuilt |
+| 503 | The owning instance closed while the request was in flight |
+
+Revocation writes a tombstone rather than deleting the entry. The tombstone persists, so a restart against a stale TOML file cannot resurrect an endpoint someone revoked. That rests on `open()` failing when the state file cannot be decoded, rather than falling back to the TOML: the connector reports the decode failure as `last_error` and serves nothing, instead of quietly putting revoked endpoints back on the wire.
+
+The 204 means the endpoint stopped serving *now*, in memory. Durability follows the same path as registration below, with one asymmetry worth knowing: losing an unsaved registration fails closed, but losing an unsaved revocation fails **open**, so the endpoint would come back after a restart.
+
+`submitted` on `GET /admin/endpoints/{id}` is not the durability check. It flips when the mutation is handed to the runtime, which happens before the runtime persists it. A save that failed shows up as `last_error` on the connector and re-arms the flush for the next poll, so treat a revocation as final only once the connector is error-free. If it cannot reach Iggy, remove the endpoint from the TOML too.
+
+Dynamic endpoints ride the SDK's `ConnectorState`, which the runtime writes after the next successful send. A management response therefore means "accepted", not "durable": if Iggy is unreachable, the endpoint is live in memory but not yet on disk, and a crash in that window loses it.
+
+`GET /admin/endpoints` reports `submitted` per endpoint. It is named that, and not `persisted`, on purpose: the flag is set when the registry is handed to the runtime, so `submitted: true` means it reached the runtime, not that the write landed.
+
+Since #3855 the runtime does acknowledge the batch, and a failed save comes back as a NACK that re-arms the flush for the next poll. The stored flag is not cleared by that re-arm, so what the API reports pairs it with whether a flush is still owed: an endpoint reads `submitted: true` only once it has been handed over and nothing is outstanding.
+
+That errs toward reporting not-yet-durable, which is the safe direction. It also means a mutation arriving after a successful save shows every endpoint as unsubmitted until the next flush lands.
+
+## Backpressure
+
+The chain below holds end to end. It did not always: the runtime's forwarding channel is unbounded, so a slow Iggy used to show up as memory growth rather than backpressure, and #3795 proposed bounding it.
+
+What closed the gap instead was #3855. The SDK now keeps one batch in flight and will not call `poll()` again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop directly. The bridge then fills on arrival and the handlers answer 429, which is the coupling that was missing.
+
+That coupling holds only while the runtime answers inside the SDK's batch-result timeout, 30s. Past it the SDK stops waiting, NACKs, and polls again, so the bridge drains and the pressure moves into the runtime's unbounded forwarding channel instead of reaching the sender. Tracked in #3981.
+
+```text
+Iggy slow -> forwarding loop blocks -> bounded channel fills -> poll() stalls
+          -> instance bridge fills -> HTTP 429 + Retry-After: 1
+```
+
+The handler never blocks on a full bridge. Waiting would hold connections open and, once the sender times out, produce a retry storm; a fast 429 tells the sender exactly what to do.
+
+| Traffic | `buffer_capacity` | Rationale |
+| ------- | ----------------- | --------- |
+| Under 100 req/s | 1000 | Small footprint |
+| 100 to 1000 req/s | 10000 (default) | Absorbs roughly ten seconds of burst |
+| Over 1000 req/s | 50000 to 100000 | Sustained bursts; tune against the buffer metrics |
+
+The bridge is bounded by message count, not bytes, so worst-case memory is `buffer_capacity * max_body_size_bytes`. At the defaults that is about 10 GB. Size the two together.

Review Comment:
   nit: this counts the bridge only. add the in-flight copies, up to three full batches (staged, sdk, runtime decoded) on top of the bridge.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On `/e/{id}` the `Bytes` extractor enforces it and the body is read before authentication, which HMAC over the raw body requires. On the named path the bearer token is checked first and the cap is applied by hand afterwards, so an unauthenticated caller never makes the process buffer. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie` — forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"service temporarily unavailable"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | Peer IP address |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 204
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only — a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |
+| ------ | --------- |
+| 400 | Empty `auth_secret`, an `expires_at` already in the past, or an `hmac_header` that is not a valid HTTP header name |
+| 401 | Missing or wrong `management_token` |
+| 404 | Unknown endpoint, unknown `instance`, or the API is not configured |
+| 409 | Rotating a static endpoint, or a generated id collision |
+| 500 | The route table could not be rebuilt |
+| 503 | The owning instance closed while the request was in flight |
+
+Revocation writes a tombstone rather than deleting the entry. The tombstone persists, so a restart against a stale TOML file cannot resurrect an endpoint someone revoked. That rests on `open()` failing when the state file cannot be decoded, rather than falling back to the TOML: the connector reports the decode failure as `last_error` and serves nothing, instead of quietly putting revoked endpoints back on the wire.
+
+The 204 means the endpoint stopped serving *now*, in memory. Durability follows the same path as registration below, with one asymmetry worth knowing: losing an unsaved registration fails closed, but losing an unsaved revocation fails **open**, so the endpoint would come back after a restart.
+
+`submitted` on `GET /admin/endpoints/{id}` is not the durability check. It flips when the mutation is handed to the runtime, which happens before the runtime persists it. A save that failed shows up as `last_error` on the connector and re-arms the flush for the next poll, so treat a revocation as final only once the connector is error-free. If it cannot reach Iggy, remove the endpoint from the TOML too.
+
+Dynamic endpoints ride the SDK's `ConnectorState`, which the runtime writes after the next successful send. A management response therefore means "accepted", not "durable": if Iggy is unreachable, the endpoint is live in memory but not yet on disk, and a crash in that window loses it.
+
+`GET /admin/endpoints` reports `submitted` per endpoint. It is named that, and not `persisted`, on purpose: the flag is set when the registry is handed to the runtime, so `submitted: true` means it reached the runtime, not that the write landed.
+
+Since #3855 the runtime does acknowledge the batch, and a failed save comes back as a NACK that re-arms the flush for the next poll. The stored flag is not cleared by that re-arm, so what the API reports pairs it with whether a flush is still owed: an endpoint reads `submitted: true` only once it has been handed over and nothing is outstanding.
+
+That errs toward reporting not-yet-durable, which is the safe direction. It also means a mutation arriving after a successful save shows every endpoint as unsubmitted until the next flush lands.
+
+## Backpressure
+
+The chain below holds end to end. It did not always: the runtime's forwarding channel is unbounded, so a slow Iggy used to show up as memory growth rather than backpressure, and #3795 proposed bounding it.
+
+What closed the gap instead was #3855. The SDK now keeps one batch in flight and will not call `poll()` again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop directly. The bridge then fills on arrival and the handlers answer 429, which is the coupling that was missing.
+
+That coupling holds only while the runtime answers inside the SDK's batch-result timeout, 30s. Past it the SDK stops waiting, NACKs, and polls again, so the bridge drains and the pressure moves into the runtime's unbounded forwarding channel instead of reaching the sender. Tracked in #3981.
+
+```text
+Iggy slow -> forwarding loop blocks -> bounded channel fills -> poll() stalls
+          -> instance bridge fills -> HTTP 429 + Retry-After: 1
+```
+
+The handler never blocks on a full bridge. Waiting would hold connections open and, once the sender times out, produce a retry storm; a fast 429 tells the sender exactly what to do.
+
+| Traffic | `buffer_capacity` | Rationale |
+| ------- | ----------------- | --------- |
+| Under 100 req/s | 1000 | Small footprint |
+| 100 to 1000 req/s | 10000 (default) | Absorbs roughly ten seconds of burst |
+| Over 1000 req/s | 50000 to 100000 | Sustained bursts; tune against the buffer metrics |
+
+The bridge is bounded by message count, not bytes, so worst-case memory is `buffer_capacity * max_body_size_bytes`. At the defaults that is about 10 GB. Size the two together.
+
+## Observability
+
+`GET /admin/health` returns per-instance JSON: queue depth and capacity, serving endpoint counts by origin plus expired and revoked counts, `state_submitted`, and header loss counters.
+
+`GET /admin/metrics` returns Prometheus text format. The runtime's own stage histograms begin at `poll()`, so they see nothing a sender experiences; these cover the gateway's own handling. The clock starts after the request body has been read, so a slow or large upload is not counted in `http_source_request_duration_seconds`.
+
+| Metric | Type | Labels | Notes |
+| ------ | ---- | ------ | ----- |
+| `http_source_requests_total` | counter | `instance`, `kind`, `status` | |
+| `http_source_request_duration_seconds` | histogram | `instance`, `status` | |
+| `http_source_rejected_full_total` | counter | `instance` | 429, the bridge was full |
+| `http_source_rejected_disconnected_total` | counter | `instance` | 503, the bridge had no receiver |
+| `http_source_dropped_on_close_total` | counter | `instance` | |
+| `http_source_headers_clamped_total` | counter | `instance` | |
+| `http_source_headers_dropped_total` | counter | `instance` | |
+| `http_source_buffer_used` | gauge | `instance` | |
+| `http_source_buffer_capacity` | gauge | `instance` | |
+| `http_source_endpoints_active` | gauge | `instance`, `kind` | endpoints that would accept a request now: neither revoked nor past `expires_at` |
+
+`kind` is `named` or `secret` for requests and `static` or `dynamic` for endpoints. `status` is the response class, `2xx`, `3xx`, `4xx`, or `5xx`, rather than the exact code, so a caller cannot inflate cardinality by probing. Only requests to a genuinely unknown path are counted under `instance="unrouted"`, which is where a scan for live endpoint ids shows up; a revoked or expired endpoint is still metered against the instance that owns it.
+
+A metric with no series yet is absent from the scrape rather than reported as zero, which is how Prometheus client libraries represent labelled families. Write dashboard queries accordingly.
+
+## Operational notes
+
+**Protect the state directory.** Once anything writes state, the file holds every endpoint's secret in the clear, static and dynamic alike, in the runtime's state path. That is the same at-rest posture as the TOML those endpoints would otherwise live in, but it means the state directory needs `chmod 700` and the same handling as any credential store.
+
+**Revocation tombstones accumulate.** They are retained deliberately, so a revocation survives a restart and stays auditable, and nothing evicts them.
+
+Each is roughly a hundred bytes and the whole registry is rewritten on every mutation, so a deployment that churns endpoints continuously will see the state file grow over time. An instance whose endpoints are all static writes no state file until something mutates its registry. Revoking a static endpoint through the management API does exactly that, and the tombstone it writes is what stops the TOML entry coming back.

Review Comment:
   nit: say what recovery looks like once a static id is revoked: re-key with a fresh `endpoint_id`, because editing the toml secret does nothing and deleting the state file also drops every dynamic endpoint.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();

Review Comment:
   nit: `instance_name` is cloned into the outcome tuple only to be borrowed again. return the `Arc<SharedState>` and label from it.
   
   also at line 630.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;

Review Comment:
   nit: three spellings for one idea: `MAX_BUFFER_CAPACITY`, `MAX_BATCH_SIZE_LIMIT`, `MAX_MAX_BODY_SIZE_BYTES`. `BUFFER_CAPACITY_LIMIT` / `MAX_BATCH_SIZE_LIMIT` / `MAX_BODY_SIZE_BYTES_LIMIT` keeps them apart from the `DEFAULT_*` values.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On `/e/{id}` the `Bytes` extractor enforces it and the body is read before authentication, which HMAC over the raw body requires. On the named path the bearer token is checked first and the cap is applied by hand afterwards, so an unauthenticated caller never makes the process buffer. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie` — forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"service temporarily unavailable"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | Peer IP address |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 204
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only — a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |
+| ------ | --------- |
+| 400 | Empty `auth_secret`, an `expires_at` already in the past, or an `hmac_header` that is not a valid HTTP header name |
+| 401 | Missing or wrong `management_token` |
+| 404 | Unknown endpoint, unknown `instance`, or the API is not configured |
+| 409 | Rotating a static endpoint, or a generated id collision |
+| 500 | The route table could not be rebuilt |
+| 503 | The owning instance closed while the request was in flight |
+
+Revocation writes a tombstone rather than deleting the entry. The tombstone persists, so a restart against a stale TOML file cannot resurrect an endpoint someone revoked. That rests on `open()` failing when the state file cannot be decoded, rather than falling back to the TOML: the connector reports the decode failure as `last_error` and serves nothing, instead of quietly putting revoked endpoints back on the wire.
+
+The 204 means the endpoint stopped serving *now*, in memory. Durability follows the same path as registration below, with one asymmetry worth knowing: losing an unsaved registration fails closed, but losing an unsaved revocation fails **open**, so the endpoint would come back after a restart.
+
+`submitted` on `GET /admin/endpoints/{id}` is not the durability check. It flips when the mutation is handed to the runtime, which happens before the runtime persists it. A save that failed shows up as `last_error` on the connector and re-arms the flush for the next poll, so treat a revocation as final only once the connector is error-free. If it cannot reach Iggy, remove the endpoint from the TOML too.
+
+Dynamic endpoints ride the SDK's `ConnectorState`, which the runtime writes after the next successful send. A management response therefore means "accepted", not "durable": if Iggy is unreachable, the endpoint is live in memory but not yet on disk, and a crash in that window loses it.
+
+`GET /admin/endpoints` reports `submitted` per endpoint. It is named that, and not `persisted`, on purpose: the flag is set when the registry is handed to the runtime, so `submitted: true` means it reached the runtime, not that the write landed.
+
+Since #3855 the runtime does acknowledge the batch, and a failed save comes back as a NACK that re-arms the flush for the next poll. The stored flag is not cleared by that re-arm, so what the API reports pairs it with whether a flush is still owed: an endpoint reads `submitted: true` only once it has been handed over and nothing is outstanding.
+
+That errs toward reporting not-yet-durable, which is the safe direction. It also means a mutation arriving after a successful save shows every endpoint as unsubmitted until the next flush lands.
+
+## Backpressure
+
+The chain below holds end to end. It did not always: the runtime's forwarding channel is unbounded, so a slow Iggy used to show up as memory growth rather than backpressure, and #3795 proposed bounding it.
+
+What closed the gap instead was #3855. The SDK now keeps one batch in flight and will not call `poll()` again until the runtime acknowledges the last one, so a slow Iggy stalls the poll loop directly. The bridge then fills on arrival and the handlers answer 429, which is the coupling that was missing.
+
+That coupling holds only while the runtime answers inside the SDK's batch-result timeout, 30s. Past it the SDK stops waiting, NACKs, and polls again, so the bridge drains and the pressure moves into the runtime's unbounded forwarding channel instead of reaching the sender. Tracked in #3981.
+
+```text
+Iggy slow -> forwarding loop blocks -> bounded channel fills -> poll() stalls

Review Comment:
   nit: the runtime forwarding channel is unbounded, as line 251 says. what stalls `poll()` is the one-batch-in-flight handshake, so fix the diagram.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {

Review Comment:
   nit: load then store, not `rcu`, so a `publish()` from join or leave landing in between is lost and the ports stay bound for good. use `self.published.rcu(..)`. needs an endpoint id collision to trigger, so low odds.



##########
core/connectors/sources/http_source/Cargo.toml:
##########
@@ -0,0 +1,62 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "iggy_connector_http_source"
+version = "0.4.1-edge.1"

Review Comment:
   nit: every sibling source is at `0.5.0-edge.4`. this was seeded from `redshift_sink`'s lineage and the bump script never converges it.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,

Review Comment:
   nit: `Option<Json<_>>` only yields `None` when content-type is absent. bad json or a wrong content-type comes back as axum's plain-text 415/400/422, not this api's `{"error":..}` shape, and the readme lists neither. take `Result<Option<Json<_>>, JsonRejection>` and route it through `error_response`.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",

Review Comment:
   nit: on the shutdown nack there is no next poll, and `close()` then logs the drop right after this line promised a replay. drop the outcome clause.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {

Review Comment:
   nit: `auth_type: none` with a secret is accepted and the secret lands in the state file in the clear. worse, `auth_type` defaults to `none`, so a misspelled key mints an unauthenticated endpoint with a 201. add `deny_unknown_fields` on the request structs and reject a secret with `none` here and in rotate.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,602 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            endpoint.submitted = true;
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked
+                && endpoint.auth_type.hmac_algorithm().is_some()
+                && HeaderName::from_str(&endpoint.hmac_header).is_err()
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id} with hmac_header '{}', which is not a valid HTTP header name; every signed request to it will be rejected until it is re-registered",
+                    endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"

Review Comment:
   nit: a restored static-origin entry is counted under `dynamic endpoints`. count by `origin`.



##########
core/connectors/sources/http_source/src/routes.rs:
##########
@@ -0,0 +1,466 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Route table for a shared listener.
+//!
+//! Every instance joining a listener contributes its named topic path and its
+//! secret-path endpoints. The merged table is rebuilt and swapped whole on
+//! join, leave, and management mutations, so a request resolves its auth
+//! requirements and its destination bridge from one wait-free snapshot.
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::fmt::{self, Display, Formatter};
+use std::sync::Arc;
+
+use crate::types::EndpointId;
+use crate::{EndpointAuthType, SharedState, StaticEndpointConfig};
+
+/// Lifecycle state of a secret-path endpoint.
+///
+/// Revocation writes a tombstone rather than deleting the entry: the tombstone
+/// persists through a restart, so a stale TOML entry can never resurrect an
+/// endpoint an operator revoked.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointState {
+    Active,
+    Revoked { reason: String, revoked_at: u64 },
+}
+
+impl EndpointState {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked { .. } => "revoked",
+        }
+    }
+}
+
+/// Where an endpoint came from, which decides whether a TOML edit plus an
+/// instance restart or a management API call is the way to change it.
+#[derive(Debug, Clone, Copy, Default, Hash, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointOrigin {
+    #[default]
+    Static,
+    Dynamic,
+}
+
+impl EndpointOrigin {
+    /// Deliberately not `Display`: the metrics encoder wants a `&str` and
+    /// would allocate one per series on every scrape.
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Static => "static",
+            Self::Dynamic => "dynamic",
+        }
+    }
+}
+
+/// A secret-path endpoint served at `POST /e/{endpoint_id}`.
+///
+/// Persisted verbatim into the runtime state directory, HMAC and bearer
+/// secrets included, so endpoints created through the management API survive a
+/// restart. That file is as sensitive as the TOML it mirrors, which is why the
+/// README requires `chmod 700` on the state path.
+/// Fields added after the first release must be APPENDED and carry
+/// `#[serde(default)]`. `ConnectorState` uses rmp's compact codec, where a
+/// struct is a positional array, so a new field without a default makes every
+/// existing state file fail to decode, and `EndpointRegistry::restore` turns a
+/// decode failure into "tombstones lost, revoked endpoints served again".
+///
+/// `auth_type` and `state` deliberately have no default: for those two, a
+/// missing element must fail the decode rather than read as an active,
+/// unauthenticated endpoint.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Endpoint {
+    pub endpoint_id: EndpointId,

Review Comment:
   nit: `endpoint_id` is both the map key and this field, and both are serialized, so a hand-edited state file can split `owner_of` from `lookup_secret_path`. overwrite the field from the key in the restore loop.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    let presented = request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(strip_bearer)
+        .map(SecretString::from);
+    match presented {
+        Some(presented) if secrets_match(&presented, expected) => None,
+        _ => Some(error_response(StatusCode::UNAUTHORIZED, "unauthorized")),
+    }
+}
+
+fn is_usable(secret: &Option<SecretString>) -> bool {
+    secret
+        .as_ref()
+        .is_some_and(|secret| !secret.expose_secret().is_empty())
+}
+
+fn owner_of(state: &ServerState, endpoint_id: &str) -> Option<Arc<SharedState>> {
+    state
+        .instances()
+        .into_iter()
+        .find(|instance| instance.registry().endpoint(endpoint_id).is_some())
+}
+
+/// Whether the instance a handler resolved earlier is still the one joined
+/// under that name. A handler awaits between resolving and mutating, and an
+/// instance can close in between - the mutation would then land on a registry
+/// nobody polls and the caller would be told it succeeded.
+fn still_joined(state: &ServerState, instance: &Arc<SharedState>) -> bool {
+    state
+        .instance(&instance.instance_name)
+        .is_some_and(|current| Arc::ptr_eq(&current, instance))
+}
+
+/// Projects the mutated registry into the shared route table.
+///
+/// A failure here leaves the registry ahead of the routes, so it answers 500
+/// rather than pretending the endpoint is live.
+async fn republish(state: &ServerState) -> Option<Response> {
+    let Err(error) = refresh_routes(&state.listen_addr).await else {
+        return None;
+    };
+    warn!(
+        "Failed to republish {CONNECTOR_NAME} routes on {}. {error}",
+        state.listen_addr
+    );
+    Some(error_response(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        "route update failed",
+    ))
+}
+
+/// Republish for a mutation that takes access AWAY. If the table cannot be
+/// rebuilt, the old one is still serving the endpoint the operator just
+/// revoked or re-keyed, so serve nothing rather than a credential they
+/// believe is dead.
+async fn republish_or_close(state: &ServerState) -> Option<Response> {
+    let failure = republish(state).await?;
+    state.serve_nothing();
+    Some(failure)
+}
+
+fn summary_response(instance: &Arc<SharedState>, endpoint_id: &str) -> Response {
+    let registry = instance.registry();
+    match registry.endpoint(endpoint_id) {
+        Some(endpoint) => Json(EndpointSummary::new(instance, endpoint)).into_response(),
+        None => error_response(StatusCode::NOT_FOUND, "not found"),
+    }
+}
+
+fn generate_endpoint_id() -> EndpointId {
+    let bytes: [u8; ENDPOINT_ID_BYTES] = rand::rng().random();
+    hex::encode(bytes)
+        .parse()
+        .expect("hex of 16 bytes is 32 lowercase hex characters")
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RegisterRequest {
+    instance: String,
+    #[serde(default)]
+    auth_type: EndpointAuthType,
+    #[serde(default)]
+    auth_secret: Option<SecretString>,
+    #[serde(default = "crate::default_hmac_header")]
+    hmac_header: String,
+    #[serde(default = "crate::default_hmac_prefix")]
+    hmac_prefix: String,
+    #[serde(default)]
+    expires_at: Option<u64>,
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RotateRequest {
+    auth_secret: SecretString,
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RevokeRequest {
+    #[serde(default)]
+    reason: Option<String>,

Review Comment:
   nit: `reason` is unbounded and persisted forever with the tombstone. cap it and answer 400 past the cap.



##########
core/connectors/runtime/example_config/connectors/http_source_github.toml:
##########
@@ -0,0 +1,60 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Instance 1 of a shared webhook listener. Pair it with
+# http_source_partner.toml to see two instances serving one port.
+#
+# The public listener binds loopback here so running the examples cannot
+# expose a port; production wants 0.0.0.0 behind a load balancer.
+
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "<BASE_DIR>/target/release/libiggy_connector_http_source"
+plugin_config_format = "toml"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_secret_token"

Review Comment:
   nit: same placeholder as `auth_bearer_token` one line up. a half-finished substitution hands every webhook sender the admin token, use a distinct placeholder like the crate's own config.toml does.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    let presented = request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(strip_bearer)
+        .map(SecretString::from);
+    match presented {
+        Some(presented) if secrets_match(&presented, expected) => None,
+        _ => Some(error_response(StatusCode::UNAUTHORIZED, "unauthorized")),
+    }
+}
+
+fn is_usable(secret: &Option<SecretString>) -> bool {
+    secret
+        .as_ref()
+        .is_some_and(|secret| !secret.expose_secret().is_empty())
+}
+
+fn owner_of(state: &ServerState, endpoint_id: &str) -> Option<Arc<SharedState>> {
+    state
+        .instances()
+        .into_iter()
+        .find(|instance| instance.registry().endpoint(endpoint_id).is_some())
+}
+
+/// Whether the instance a handler resolved earlier is still the one joined
+/// under that name. A handler awaits between resolving and mutating, and an
+/// instance can close in between - the mutation would then land on a registry
+/// nobody polls and the caller would be told it succeeded.
+fn still_joined(state: &ServerState, instance: &Arc<SharedState>) -> bool {
+    state
+        .instance(&instance.instance_name)
+        .is_some_and(|current| Arc::ptr_eq(&current, instance))
+}
+
+/// Projects the mutated registry into the shared route table.
+///
+/// A failure here leaves the registry ahead of the routes, so it answers 500
+/// rather than pretending the endpoint is live.
+async fn republish(state: &ServerState) -> Option<Response> {
+    let Err(error) = refresh_routes(&state.listen_addr).await else {
+        return None;
+    };
+    warn!(
+        "Failed to republish {CONNECTOR_NAME} routes on {}. {error}",
+        state.listen_addr
+    );
+    Some(error_response(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        "route update failed",
+    ))
+}
+
+/// Republish for a mutation that takes access AWAY. If the table cannot be
+/// rebuilt, the old one is still serving the endpoint the operator just
+/// revoked or re-keyed, so serve nothing rather than a credential they
+/// believe is dead.
+async fn republish_or_close(state: &ServerState) -> Option<Response> {
+    let failure = republish(state).await?;
+    state.serve_nothing();
+    Some(failure)
+}
+
+fn summary_response(instance: &Arc<SharedState>, endpoint_id: &str) -> Response {
+    let registry = instance.registry();
+    match registry.endpoint(endpoint_id) {
+        Some(endpoint) => Json(EndpointSummary::new(instance, endpoint)).into_response(),
+        None => error_response(StatusCode::NOT_FOUND, "not found"),
+    }
+}
+
+fn generate_endpoint_id() -> EndpointId {
+    let bytes: [u8; ENDPOINT_ID_BYTES] = rand::rng().random();
+    hex::encode(bytes)
+        .parse()
+        .expect("hex of 16 bytes is 32 lowercase hex characters")
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RegisterRequest {
+    instance: String,
+    #[serde(default)]
+    auth_type: EndpointAuthType,
+    #[serde(default)]
+    auth_secret: Option<SecretString>,
+    #[serde(default = "crate::default_hmac_header")]
+    hmac_header: String,
+    #[serde(default = "crate::default_hmac_prefix")]
+    hmac_prefix: String,
+    #[serde(default)]
+    expires_at: Option<u64>,
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RotateRequest {
+    auth_secret: SecretString,
+}
+
+// Unlike the plugin config, these never carry the runtime's flat env
+// overrides, so a rejected unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RevokeRequest {
+    #[serde(default)]
+    reason: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+struct RegisteredEndpoint {
+    endpoint_id: EndpointId,
+    path: String,
+}
+
+/// The operator-facing view of an endpoint. Carries no secret, which is why
+/// it exists rather than serializing [`Endpoint`] directly.
+#[derive(Debug, Serialize)]
+struct EndpointSummary {
+    endpoint_id: EndpointId,
+    instance: String,
+    state: &'static str,

Review Comment:
   nit: the summary omits `hmac_header` and `hmac_prefix`, so an operator debugging 401s cannot see which header the endpoint expects. neither is secret, add both.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),
+        headers,
+    };
+    if let Err(error) = instance.sender.try_send(message) {
+        // A disconnected bridge is not a full one. It cannot happen while the
+        // route table holds an `Arc` to this `SharedState`, but reporting it as
+        // backpressure would tell a sender to retry into a channel that no
+        // longer has a receiver, and would file the loss under the wrong metric.
+        if matches!(error, crossfire::TrySendError::Disconnected(_)) {
+            metrics.record_rejected_disconnected(&instance.instance_name);
+            error!(
+                "Rejected a request for {CONNECTOR_NAME} connector ID: {}, its bridge has no receiver",
+                instance.id
+            );
+            return (
+                StatusCode::SERVICE_UNAVAILABLE,
+                Json(ErrorResponse {
+                    error: "service unavailable",
+                }),
+            )
+                .into_response();
+        }
+        metrics.record_rejected_full(&instance.instance_name);
+        debug!(
+            "Rejected a request for {CONNECTOR_NAME} connector ID: {}, bridge is full at {} messages",
+            instance.id, instance.config.buffer_capacity
+        );
+        return (
+            StatusCode::TOO_MANY_REQUESTS,
+            [(header::RETRY_AFTER, "1")],

Review Comment:
   nit: bare `"1"`, duplicated in the test at line 1189. name it.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",

Review Comment:
   nit: `status` is always `"ok"`, even with no instance polling while `/health` says 503. drop it or derive it.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |

Review Comment:
   nit: env overrides coerce numeric-looking values, so `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` fails the whole config parse with a message that names no field. worth a note here.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,

Review Comment:
   nit: `http_sink` calls the same knob `max_payload_size_bytes`. the sink name is shipped, so either adopt it or document the difference.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,

Review Comment:
   nit: `HeaderMap` as an extractor is a clone of the request headers, and the named path clones by hand at line 556. `into_parts()` gives you them owned.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),

Review Comment:
   nit: `header::AUTHORIZATION`, `PROXY_AUTHORIZATION` and `COOKIE` exist and server.rs line 907 already uses the first. compare against them (`==`, not `matches!`).



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,317 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On `/e/{id}` the `Bytes` extractor enforces it and the body is read before authentication, which HMAC over the raw body requires. On the named path the bearer token is checked first and the cap is applied by hand afterwards, so an unauthenticated caller never makes the process buffer. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie` — forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"service temporarily unavailable"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | Peer IP address |

Review Comment:
   nit: this is the tcp peer, so behind the proxy line 307 recommends it is always the proxy ip. point at `forward_headers = ["X-Forwarded-For"]`.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())

Review Comment:
   nit: returning `String` makes axum send `text/plain`, but the body is openmetrics with an `# EOF` trailer. set `application/openmetrics-text; version=1.0.0; charset=utf-8`.



##########
core/connectors/sources/http_source/src/metrics.rs:
##########
@@ -0,0 +1,465 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Gateway-side Prometheus metrics, served on the admin listener.
+//!
+//! The runtime's own stage histograms start at `poll()`, so they cannot see
+//! anything a webhook sender experiences. This connector is an HTTP server, so
+//! it measures its own handling: the clock starts once axum has run the
+//! extractors, which means the request body has already been read. Time spent
+//! receiving a slow or large upload therefore sits outside the histogram, and
+//! accept-to-200 would need a tower layer wrapping the extractors.
+//!
+//! Names carry an `http_source_` prefix to keep them clear of the runtime's
+//! `iggy_connector_` family. One registry per shared listener, with every
+//! series labelled by instance.
+
+use prometheus_client::encoding::text::encode;
+use prometheus_client::encoding::{EncodeLabelSet, EncodeLabelValue, LabelValueEncoder};
+use prometheus_client::metrics::counter::Counter;
+use prometheus_client::metrics::family::Family;
+use prometheus_client::metrics::gauge::Gauge;
+use prometheus_client::metrics::histogram::Histogram;
+use prometheus_client::registry::Registry;
+use std::fmt;
+use std::sync::Arc;
+use std::time::Duration;
+use tracing::error;
+
+use crate::SharedState;
+use crate::routes::EndpointOrigin;
+use crate::types::unix_now_seconds;
+
+/// Instance label for requests that never resolved to one, so a scan for
+/// live endpoint ids still shows up rather than going uncounted.
+pub const UNROUTED: &str = "unrouted";
+
+/// Sub-millisecond at the low end: accepting a webhook is a route lookup, a
+/// signature check, and a channel send, so the interesting range is tight.
+const REQUEST_BUCKETS_SECONDS: [f64; 12] = [
+    50e-6, 100e-6, 250e-6, 500e-6, 1e-3, 2.5e-3, 5e-3, 10e-3, 25e-3, 50e-3, 100e-3, 500e-3,
+];
+
+/// Which surface a request arrived on.
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum PathKind {
+    Named,
+    Secret,
+}
+
+/// Response class, coarse on purpose: a per-status-code label would let a
+/// caller inflate cardinality by probing.
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum StatusClass {
+    Success,
+    Redirect,
+    ClientError,
+    ServerError,
+}
+
+impl From<u16> for StatusClass {
+    fn from(status: u16) -> Self {
+        match status {
+            200..=299 => Self::Success,
+            300..=399 => Self::Redirect,
+            400..=499 => Self::ClientError,
+            _ => Self::ServerError,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct InstanceLabel {
+    pub instance: String,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct RequestLabels {
+    pub instance: String,
+    pub kind: PathKind,
+    pub status: StatusClass,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct DurationLabels {
+    pub instance: String,
+    pub status: StatusClass,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct EndpointLabels {
+    pub instance: String,
+    pub kind: EndpointOrigin,
+}
+
+#[derive(Debug)]
+pub struct Metrics {
+    registry: Registry,
+    requests: Family<RequestLabels, Counter>,
+    request_duration_seconds: Family<DurationLabels, Histogram, fn() -> Histogram>,
+    rejected_full: Family<InstanceLabel, Counter>,
+    rejected_disconnected: Family<InstanceLabel, Counter>,
+    dropped_on_close: Family<InstanceLabel, Counter>,
+    headers_clamped: Family<InstanceLabel, Counter>,
+    headers_dropped: Family<InstanceLabel, Counter>,
+    buffer_used: Family<InstanceLabel, Gauge>,
+    buffer_capacity: Family<InstanceLabel, Gauge>,
+    endpoints_active: Family<EndpointLabels, Gauge>,
+}
+
+impl Metrics {
+    pub fn new() -> Self {
+        let mut registry = Registry::default();
+        let requests = Family::<RequestLabels, Counter>::default();
+        let request_duration_seconds: Family<DurationLabels, Histogram, fn() -> Histogram> =
+            Family::new_with_constructor(request_histogram);
+        let rejected_full = Family::<InstanceLabel, Counter>::default();
+        let rejected_disconnected = Family::<InstanceLabel, Counter>::default();
+        let dropped_on_close = Family::<InstanceLabel, Counter>::default();
+        let headers_clamped = Family::<InstanceLabel, Counter>::default();
+        let headers_dropped = Family::<InstanceLabel, Counter>::default();
+        let buffer_used = Family::<InstanceLabel, Gauge>::default();
+        let buffer_capacity = Family::<InstanceLabel, Gauge>::default();
+        let endpoints_active = Family::<EndpointLabels, Gauge>::default();
+
+        registry.register(
+            "http_source_requests",
+            "Webhook requests by path kind and response class",
+            requests.clone(),
+        );
+        registry.register(
+            "http_source_request_duration_seconds",
+            "Time from request accepted to response, in seconds",
+            request_duration_seconds.clone(),
+        );
+        registry.register(
+            "http_source_rejected_full",
+            "Requests answered 429 because the instance bridge was full",
+            rejected_full.clone(),
+        );
+        registry.register(
+            "http_source_rejected_disconnected",
+            "Requests answered 503 because the instance bridge had no receiver",
+            rejected_disconnected.clone(),
+        );
+        registry.register(
+            "http_source_dropped_on_close",
+            "Accepted messages still queued when the instance closed",
+            dropped_on_close.clone(),
+        );
+        registry.register(
+            "http_source_headers_clamped",
+            "Forwarded header values truncated to the Iggy 255-byte limit",
+            headers_clamped.clone(),
+        );
+        registry.register(
+            "http_source_headers_dropped",
+            "Forwarded header values Iggy would have rejected outright",
+            headers_dropped.clone(),
+        );
+        registry.register(
+            "http_source_buffer_used",
+            "Messages queued in the instance bridge",
+            buffer_used.clone(),
+        );
+        registry.register(
+            "http_source_buffer_capacity",
+            "Configured capacity of the instance bridge",
+            buffer_capacity.clone(),
+        );
+        registry.register(
+            "http_source_endpoints_active",
+            "Secret-path endpoints currently accepting requests, by origin",
+            endpoints_active.clone(),
+        );
+
+        Metrics {
+            registry,
+            requests,
+            request_duration_seconds,
+            rejected_full,
+            rejected_disconnected,
+            dropped_on_close,
+            headers_clamped,
+            headers_dropped,
+            buffer_used,
+            buffer_capacity,
+            endpoints_active,
+        }
+    }
+
+    /// Labels are built per call rather than cached per instance: one small
+    /// `String` clone is noise next to copying the request body, and the
+    /// cache would have to cover every kind and status combination.
+    pub fn record_request(&self, instance: &str, kind: PathKind, status: u16, elapsed: Duration) {
+        let status = StatusClass::from(status);
+        self.requests
+            .get_or_create(&RequestLabels {
+                instance: instance.to_owned(),
+                kind,
+                status,
+            })
+            .inc();
+        self.request_duration_seconds
+            .get_or_create(&DurationLabels {
+                instance: instance.to_owned(),
+                status,
+            })
+            .observe(elapsed.as_secs_f64());
+    }
+
+    pub fn record_rejected_full(&self, instance: &str) {
+        self.rejected_full.get_or_create(&label(instance)).inc();
+    }
+
+    /// Separate from `rejected_full` on purpose: backpressure tells a sender to
+    /// retry, a bridge with no receiver never will, and folding them together
+    /// would hide the second inside the first.
+    pub fn record_rejected_disconnected(&self, instance: &str) {
+        self.rejected_disconnected
+            .get_or_create(&label(instance))
+            .inc();
+    }
+
+    pub fn record_dropped_on_close(&self, instance: &str, dropped: u64) {
+        self.dropped_on_close
+            .get_or_create(&label(instance))
+            .inc_by(dropped);
+    }
+
+    pub fn record_headers(&self, instance: &str, clamped: u64, dropped: u64) {
+        if clamped > 0 {
+            self.headers_clamped
+                .get_or_create(&label(instance))
+                .inc_by(clamped);
+        }
+        if dropped > 0 {
+            self.headers_dropped
+                .get_or_create(&label(instance))
+                .inc_by(dropped);
+        }
+    }
+
+    /// Reads without creating. `get_or_create` would materialise a zero
+    /// series as a side effect, so an admin health check would make counters
+    /// appear in every later scrape - contradicting the documented rule that
+    /// an untouched family is absent rather than zero.
+    pub fn headers_clamped(&self, instance: &str) -> u64 {
+        self.headers_clamped
+            .get(&label(instance))
+            .map_or(0, |counter| counter.get())
+    }
+
+    pub fn headers_dropped(&self, instance: &str) -> u64 {
+        self.headers_dropped
+            .get(&label(instance))
+            .map_or(0, |counter| counter.get())
+    }
+
+    /// Refreshes the sampled gauges and renders the Prometheus text format.
+    ///
+    /// The gauges are read from the instances at scrape time rather than
+    /// maintained on the hot path: queue depth and endpoint counts are only
+    /// meaningful as instantaneous values, and nothing observes them between
+    /// scrapes.
+    pub fn encode(&self, instances: &[Arc<SharedState>]) -> String {
+        // Cleared and rebuilt, so a scrape is always exactly the live set.
+        // These are instantaneous readings, so a departed instance's queue
+        // depth is not merely stale but meaningless, and reconciling here is
+        // what keeps that impossible. Counters are untouched: they are
+        // cumulative and their last value stays true after an instance goes.
+        self.buffer_used.clear();
+        self.buffer_capacity.clear();

Review Comment:
   nit: `encode` clears these three gauge families and refills them from the instance list, so two scrapes at once can render them empty or half filled. build the values first and store in one pass.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),
+        headers,
+    };
+    if let Err(error) = instance.sender.try_send(message) {
+        // A disconnected bridge is not a full one. It cannot happen while the
+        // route table holds an `Arc` to this `SharedState`, but reporting it as
+        // backpressure would tell a sender to retry into a channel that no
+        // longer has a receiver, and would file the loss under the wrong metric.
+        if matches!(error, crossfire::TrySendError::Disconnected(_)) {
+            metrics.record_rejected_disconnected(&instance.instance_name);
+            error!(
+                "Rejected a request for {CONNECTOR_NAME} connector ID: {}, its bridge has no receiver",
+                instance.id
+            );
+            return (
+                StatusCode::SERVICE_UNAVAILABLE,
+                Json(ErrorResponse {
+                    error: "service unavailable",
+                }),
+            )
+                .into_response();
+        }
+        metrics.record_rejected_full(&instance.instance_name);
+        debug!(
+            "Rejected a request for {CONNECTOR_NAME} connector ID: {}, bridge is full at {} messages",
+            instance.id, instance.config.buffer_capacity
+        );
+        return (
+            StatusCode::TOO_MANY_REQUESTS,
+            [(header::RETRY_AFTER, "1")],
+            Json(ErrorResponse {
+                error: "service temporarily unavailable",

Review Comment:
   nit: this is a one-word variant of the 503 body at line 764. say `too many requests` so log greps tell them apart, and update the readme row.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(

Review Comment:
   simplification: with `handle_secret_path` taking `Request` and calling `to_bytes` itself, `DefaultBodyLimit` on the public router, the `BytesRejection` import and `rejected_body_response` all go. the named path stays as it is.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,

Review Comment:
   simplification: this lock is never held across an await, so `std::sync::Mutex` works and `mutate_registry` can be sync, dropping ten awaits. keep the `try_lock` in `take_dirty_state` though, a blocking lock there would stall a worker across the registry clone.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1695 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const MAX_BUFFER_CAPACITY: usize = 1_000_000;
+/// Bounds the `Vec::with_capacity(max_batch_size)` that every `poll()` builds
+/// up front, which is what an oversized value actually costs.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_MAX_BODY_SIZE_BYTES: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub async fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and marks every endpoint submitted
+    /// before the state leaves the plugin, so a caller that later learns the
+    /// save did not land has to put the flag back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        self.state_flush.notify_one();
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag and marked the registry submitted, losing a
+    /// revocation tombstone with no trace. An empty batch cannot fail *for
+    /// want of a successful publish*, which is what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > MAX_BUFFER_CAPACITY {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {MAX_BUFFER_CAPACITY}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_MAX_BODY_SIZE_BYTES {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_MAX_BODY_SIZE_BYTES}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, MAX_BUFFER_CAPACITY);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty, and
+            // re-arming then costs one redundant flush rather than a lost one. `take_dirty_state` already cleared
+            // the flag and marked every endpoint submitted, so re-arming here
+            // is the only thing that stops a revocation being lost while the
+            // API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",
+            self.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        tokio::select! {
+            // The SDK races poll() against its own shutdown watch, so blocking
+            // here until traffic arrives is what keeps an idle gateway off the
+            // CPU. crossfire documents recv() as cancellation-safe.
+            received = receiver.recv() => match received {
+                Ok(message) => {
+                    queued.push(message);
+                    while queued.len() < max_batch_size {
+                        let Ok(message) = receiver.try_recv() else {
+                            break;
+                        };
+                        queued.push(message);
+                    }
+                }
+                // Reachable only once every sender is gone. Idle rather than
+                // spin the SDK's poll loop.
+                Err(_) => tokio::time::sleep(IDLE_POLL_INTERVAL).await,

Review Comment:
   simplification: this arm is unreachable, `recv()` only errs once every sender is dropped and the sender lives in `self.shared`. make it `Err(_) => {}` and delete `IDLE_POLL_INTERVAL`.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {

Review Comment:
   simplification: the `Revoked` and `Expired` arms are identical, and the comment in routes.rs promising to meter them apart is not honoured here. merge them into one arm, or actually meter them.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.published.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+        // Instances are kept: they are still joined and still own bridges, and
+        // it is only the routing that is being withdrawn.
+        self.published.store(Arc::new(Published {
+            instances: dropped.instances.clone(),
+            routes: RouteTable::default(),
+        }));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its listen_addr must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (String, Response) {
+    // Cloned before the body is taken, since reading it consumes the request.
+    let request_headers = request.headers().clone();
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        };
+        Arc::clone(instance)
+    };
+    let name = instance.instance_name.clone();
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(request.into_body(), state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (name, oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = &state.published().routes;
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        // Expired answers 404 for the same reason revoked does. A 410 would
+        // be returned before any credential is checked, so it would tell anyone
+        // holding a leaked or guessed id that the endpoint had once been real.
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+///
+/// A joined instance is not the same as a polling one. The SDK stops the poll
+/// task after five consecutive NACKs without calling `close()`, so the instance
+/// stays joined and this kept answering 200 to the load balancer while handlers
+/// accepted into a bridge nobody drained, until it filled and 429d forever.
+/// Readiness needs all three: an instance, a route it can reach, and a poll
+/// task still running behind it.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    let now = unix_now_seconds();
+    // One guard for both, so readiness cannot be computed from a route table
+    // and an instance set that were never published together.
+    let published = state.published();
+    let instances = &published.instances;
+    // Every instance, not any. One load balancer fronts the whole listener, so
+    // it can only take all of these in or out together. If one instance's poll
+    // task has stopped while a sibling's is alive, `any` keeps the address in
+    // rotation and the dead one's webhooks are accepted into a bridge nobody
+    // drains, which is the exact failure this gate exists to catch. Shedding
+    // the healthy sibling's traffic too costs availability that senders recover
+    // by retrying; the alternative loses data that was already answered 200.
+    let ready = published.routes.serves_anything(now)
+        && !instances.is_empty()
+        && instances.iter().all(|instance| instance.poll_is_live(now));
+    if !ready {
+        return (
+            StatusCode::SERVICE_UNAVAILABLE,
+            Json(StatusResponse {
+                status: "unavailable",
+            }),
+        )
+            .into_response();
+    }
+    Json(StatusResponse { status: "ok" }).into_response()
+}
+
+async fn handle_admin_health(State(state): State<Arc<ServerState>>) -> Response {
+    let instances = state
+        .published()
+        .instances
+        .iter()
+        .map(|instance| {
+            let registry = instance.registry();
+            let now = unix_now_seconds();
+            InstanceHealth {
+                instance: instance.instance_name.clone(),
+                topic_path: instance.config.topic_path.clone(),
+                buffer_used: instance.sender.len(),
+                buffer_capacity: instance.config.buffer_capacity,
+                endpoints_static: registry.serving_count_by_origin(EndpointOrigin::Static, now),
+                endpoints_dynamic: registry.serving_count_by_origin(EndpointOrigin::Dynamic, now),
+                endpoints_expired: registry.expired_count(now),
+                endpoints_revoked: registry.revoked_count(),
+                named_path: instance.config.topic_path.is_some(),
+                // Same derivation as the per-endpoint flag: submitted is set
+                // before the state leaves, so it only means durable if no
+                // flush is still owed.
+                state_submitted: registry.all_submitted() && !instance.has_pending_state(),
+                dropped_headers: state.metrics.headers_dropped(&instance.instance_name),
+                clamped_headers: state.metrics.headers_clamped(&instance.instance_name),
+            }
+        })
+        .collect();
+
+    Json(AdminHealth {
+        status: "ok",
+        instances,
+        uptime_secs: state.started_at.elapsed().as_secs(),
+    })
+    .into_response()
+}
+
+/// Hands an accepted request to its instance's bridge, or rejects it.
+///
+/// Never blocks on a full bridge: waiting would turn a slow Iggy into a pile
+/// of held-open connections and, once the sender times out, a retry storm.
+fn enqueue(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+    body: Bytes,
+    metrics: &Metrics,
+) -> Response {
+    let (headers, clamped, dropped) = message_headers(instance, request_headers, remote_addr);
+    let message = QueuedMessage {
+        // `to_vec`, deliberately, not `Vec::from(body)`. The latter hands back
+        // hyper's read buffer, which at typical webhook sizes is several times
+        // the body, and the bridge is bounded by message count rather than
+        // bytes. Copying the exact length is what keeps `buffer_capacity`
+        // meaning what an operator thinks it means.
+        payload: body.to_vec(),
+        headers,
+    };
+    if let Err(error) = instance.sender.try_send(message) {
+        // A disconnected bridge is not a full one. It cannot happen while the
+        // route table holds an `Arc` to this `SharedState`, but reporting it as
+        // backpressure would tell a sender to retry into a channel that no
+        // longer has a receiver, and would file the loss under the wrong metric.
+        if matches!(error, crossfire::TrySendError::Disconnected(_)) {
+            metrics.record_rejected_disconnected(&instance.instance_name);
+            error!(
+                "Rejected a request for {CONNECTOR_NAME} connector ID: {}, its bridge has no receiver",
+                instance.id
+            );
+            return (
+                StatusCode::SERVICE_UNAVAILABLE,
+                Json(ErrorResponse {
+                    error: "service unavailable",
+                }),
+            )
+                .into_response();
+        }
+        metrics.record_rejected_full(&instance.instance_name);
+        debug!(
+            "Rejected a request for {CONNECTOR_NAME} connector ID: {}, bridge is full at {} messages",
+            instance.id, instance.config.buffer_capacity
+        );
+        return (
+            StatusCode::TOO_MANY_REQUESTS,
+            [(header::RETRY_AFTER, "1")],
+            Json(ErrorResponse {
+                error: "service temporarily unavailable",
+            }),
+        )
+            .into_response();
+    }
+    // Only now: a rejected request produced no message, so its header losses
+    // would otherwise be counted against messages that never existed.
+    metrics.record_headers(&instance.instance_name, clamped, dropped);
+    Json(StatusResponse { status: "queued" }).into_response()
+}
+
+fn authorize(endpoint: &Endpoint, request_headers: &HeaderMap, body: &[u8]) -> bool {
+    match endpoint.auth_type {
+        EndpointAuthType::None => true,
+        EndpointAuthType::Bearer => endpoint
+            .auth_secret
+            .as_ref()
+            .is_some_and(|secret| validate_bearer(bearer_header(request_headers), secret)),
+        EndpointAuthType::HmacSha256 | EndpointAuthType::HmacSha1 => {
+            let (Some(secret), Some(algorithm)) = (
+                endpoint.auth_secret.as_ref(),
+                endpoint.auth_type.hmac_algorithm(),
+            ) else {
+                return false;
+            };
+            validate_hmac(
+                body,
+                header_str(request_headers, &endpoint.hmac_header),
+                &endpoint.hmac_prefix,
+                secret,
+                algorithm,
+            )
+        }
+    }
+}
+
+/// Builds the Iggy headers an accepted request rides with.
+///
+/// Values Iggy would reject are dropped rather than failing the message: a
+/// webhook body is worth more than a `User-Agent`.
+///
+/// Returns the headers to attach plus the number of forwarded values that were
+/// truncated and dropped. The counts are returned rather than recorded here so
+/// a request that is ultimately rejected does not report losses for a message
+/// that was never produced.
+fn message_headers(
+    instance: &Arc<SharedState>,
+    request_headers: &HeaderMap,
+    remote_addr: SocketAddr,
+) -> (Option<BTreeMap<HeaderKey, HeaderValue>>, u64, u64) {
+    let mut headers = BTreeMap::new();
+    let mut dropped = 0;
+    let mut clamped = 0;
+    if instance.config.include_http_metadata {
+        insert_header(&mut headers, &INSTANCE_HEADER_KEY, &instance.instance_name);
+        insert_header(
+            &mut headers,
+            &REMOTE_ADDR_HEADER_KEY,
+            &remote_addr.ip().to_string(),
+        );
+        if let Some(received_at) = received_at_micros() {
+            insert_header(&mut headers, &RECEIVED_AT_HEADER_KEY, &received_at);
+        }
+    }
+
+    for (name, key) in &instance.forward_headers {
+        let Some(present) = request_headers.get(name) else {
+            continue;
+        };
+        // Present but unrepresentable is a loss; absent is not. `to_str`
+        // rejects any byte outside visible ASCII, which a UTF-8 User-Agent
+        // routinely carries.
+        let Ok(raw) = present.to_str() else {
+            dropped += 1;
+            continue;
+        };
+        let Some(value) = clamp_header_value(raw) else {
+            dropped += 1;
+            continue;
+        };
+        if value.len() < raw.len() {
+            clamped += 1;
+        }
+        match HeaderValue::from_str(value) {
+            Ok(value) => {
+                headers.insert(key.clone(), value);
+            }
+            Err(_) => dropped += 1,
+        }
+    }
+    ((!headers.is_empty()).then_some(headers), clamped, dropped)
+}
+
+/// The three metadata keys, parsed once. They are compile-time constants, so
+/// re-parsing them per request repeated validation that can only ever succeed,
+/// the same reason `forward_headers` is resolved at construction.
+static INSTANCE_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(INSTANCE_HEADER).ok());
+static REMOTE_ADDR_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(REMOTE_ADDR_HEADER).ok());
+static RECEIVED_AT_HEADER_KEY: LazyLock<Option<HeaderKey>> =
+    LazyLock::new(|| HeaderKey::try_from(RECEIVED_AT_HEADER).ok());
+
+fn insert_header(
+    headers: &mut BTreeMap<HeaderKey, HeaderValue>,
+    key: &Option<HeaderKey>,
+    value: &str,
+) {
+    let (Some(key), Ok(value)) = (key.as_ref(), HeaderValue::from_str(value)) else {
+        return;
+    };
+    headers.insert(key.clone(), value);
+}
+
+/// `None` when the clock predates the epoch, which is the only way this fails.
+///
+/// Defaulting to 0 would stamp every message with the epoch, and the header
+/// exists so a consumer can measure queue latency, so a plausible wrong value
+/// is worse than an absent one. `unix_now_seconds` saturates instead because
+/// its callers gate on expiry, where failing closed is the safe direction.
+fn received_at_micros() -> Option<String> {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .ok()
+        .map(|elapsed| elapsed.as_micros().to_string())
+}
+
+fn bearer_header(request_headers: &HeaderMap) -> Option<&str> {
+    request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+}
+
+fn header_str<'a>(request_headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
+    request_headers
+        .get(name)
+        .and_then(|value| value.to_str().ok())
+}
+
+/// `to_bytes` reports the cap and a truncated stream through the same error, so
+/// the status mirrors what the `Bytes` extractor would have returned: a body
+/// that ran past the limit is 413, anything else is a 400.
+fn oversized_body_response(error: &axum::Error) -> Response {
+    let too_large = error
+        .to_string()
+        .to_ascii_lowercase()
+        .contains("length limit exceeded");
+    if too_large {
+        error_response(StatusCode::PAYLOAD_TOO_LARGE, "payload too large")
+    } else {
+        error_response(StatusCode::BAD_REQUEST, "bad request")
+    }
+}
+
+fn rejected_body_response(rejection: BytesRejection) -> Response {
+    let status = rejection.status();
+    let message = if status == StatusCode::PAYLOAD_TOO_LARGE {
+        "payload too large"
+    } else {
+        "bad request"
+    };
+    error_response(status, message)
+}
+
+pub(crate) fn error_response(status: StatusCode, error: &'static str) -> Response {
+    (status, Json(ErrorResponse { error })).into_response()
+}
+
+#[derive(Serialize)]
+struct StatusResponse {
+    status: &'static str,
+}
+
+#[derive(Serialize)]
+struct ErrorResponse {
+    error: &'static str,
+}
+
+#[derive(Serialize)]
+struct AdminHealth {
+    status: &'static str,
+    instances: Vec<InstanceHealth>,
+    uptime_secs: u64,
+}
+
+#[derive(Serialize)]
+struct InstanceHealth {
+    instance: String,
+    topic_path: Option<String>,
+    buffer_used: usize,
+    buffer_capacity: usize,
+    endpoints_static: usize,
+    endpoints_dynamic: usize,
+    endpoints_expired: usize,
+    endpoints_revoked: usize,
+    named_path: bool,
+    state_submitted: bool,
+    dropped_headers: u64,

Review Comment:
   nit: `dropped_headers` / `clamped_headers` invert the metric names `headers_dropped` / `headers_clamped`. align them.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1977 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,

Review Comment:
   simplification: `ServerState` already holds `max_body_size_bytes`, and could hold `admin_listen_addr` too. read both from `self.state` in `ensure_compatible` and drop the duplicates.



##########
core/connectors/sources/http_source/src/routes.rs:
##########
@@ -0,0 +1,466 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Route table for a shared listener.
+//!
+//! Every instance joining a listener contributes its named topic path and its
+//! secret-path endpoints. The merged table is rebuilt and swapped whole on
+//! join, leave, and management mutations, so a request resolves its auth
+//! requirements and its destination bridge from one wait-free snapshot.
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::fmt::{self, Display, Formatter};
+use std::sync::Arc;
+
+use crate::types::EndpointId;
+use crate::{EndpointAuthType, SharedState, StaticEndpointConfig};
+
+/// Lifecycle state of a secret-path endpoint.
+///
+/// Revocation writes a tombstone rather than deleting the entry: the tombstone
+/// persists through a restart, so a stale TOML entry can never resurrect an
+/// endpoint an operator revoked.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointState {
+    Active,
+    Revoked { reason: String, revoked_at: u64 },
+}
+
+impl EndpointState {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked { .. } => "revoked",
+        }
+    }
+}
+
+/// Where an endpoint came from, which decides whether a TOML edit plus an
+/// instance restart or a management API call is the way to change it.
+#[derive(Debug, Clone, Copy, Default, Hash, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointOrigin {
+    #[default]
+    Static,
+    Dynamic,
+}
+
+impl EndpointOrigin {
+    /// Deliberately not `Display`: the metrics encoder wants a `&str` and
+    /// would allocate one per series on every scrape.
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Static => "static",
+            Self::Dynamic => "dynamic",
+        }
+    }
+}
+
+/// A secret-path endpoint served at `POST /e/{endpoint_id}`.
+///
+/// Persisted verbatim into the runtime state directory, HMAC and bearer
+/// secrets included, so endpoints created through the management API survive a
+/// restart. That file is as sensitive as the TOML it mirrors, which is why the
+/// README requires `chmod 700` on the state path.
+/// Fields added after the first release must be APPENDED and carry
+/// `#[serde(default)]`. `ConnectorState` uses rmp's compact codec, where a
+/// struct is a positional array, so a new field without a default makes every
+/// existing state file fail to decode, and `EndpointRegistry::restore` turns a
+/// decode failure into "tombstones lost, revoked endpoints served again".
+///
+/// `auth_type` and `state` deliberately have no default: for those two, a
+/// missing element must fail the decode rather than read as an active,
+/// unauthenticated endpoint.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Endpoint {
+    pub endpoint_id: EndpointId,
+    // No default, for symmetry with `state` rather than because it can save
+    // us: msgpack compact encodes this struct as a positional array, so a
+    // record can only be short from the end, and this sits second of eight.
+    // `state` is last, which is why the guard there is the one that works.
+    pub auth_type: EndpointAuthType,
+    #[serde(default, serialize_with = "crate::state::serialize_secret_to_state")]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default)]
+    pub hmac_header: String,
+    #[serde(default)]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+    #[serde(default)]
+    pub origin: EndpointOrigin,
+    // No default: `EndpointState::default()` would be `Active`, so a record
+    // short by one element would resurrect a revoked endpoint - turning a
+    // loud decode failure into a silent, fail-open one.
+    pub state: EndpointState,
+    /// Whether this endpoint has been handed to the runtime for persistence.
+    /// Reset on every mutation, never itself persisted: a restored endpoint is
+    /// durable by definition. Not named `persisted`, because the plugin gets
+    /// no acknowledgement that the runtime's write actually landed.
+    #[serde(skip)]
+    pub submitted: bool,

Review Comment:
   simplification: `submitted` equals `!has_pending_state()` everywhere it is read, except in two small windows where the dirty flag lags the publish. fold the dirty store into the publish, then drop the field, `mark_submitted`, `all_submitted` and one registry clone per flush.



##########
core/connectors/sources/http_source/src/auth.rs:
##########
@@ -0,0 +1,267 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::sync::LazyLock;
+
+/// HMAC algorithms accepted for signature validation. SHA-256 covers GitHub,
+/// Stripe, and most modern providers; SHA-1 exists only for legacy senders.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum HmacAlgorithm {
+    HmacSha256,
+    HmacSha1,
+}
+
+impl HmacAlgorithm {
+    fn ring_algorithm(self) -> hmac::Algorithm {
+        match self {
+            Self::HmacSha256 => hmac::HMAC_SHA256,
+            Self::HmacSha1 => hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY,
+        }
+    }
+}
+
+/// Validates `Authorization: Bearer <token>` in constant time.
+pub fn validate_bearer(authorization_header: Option<&str>, expected_token: &SecretString) -> bool {
+    let Some(header_value) = authorization_header else {
+        return false;
+    };
+    let Some(presented_token) = strip_bearer(header_value) else {
+        return false;
+    };
+    constant_time_eq(
+        presented_token.as_bytes(),
+        expected_token.expose_secret().as_bytes(),
+    )
+}
+
+/// Splits `Bearer <token>`. RFC 7235 makes the scheme case-insensitive, so a
+/// sender using `bearer` is legitimate and must not be turned away.
+pub fn strip_bearer(header_value: &str) -> Option<&str> {
+    let (scheme, token) = header_value.split_once(' ')?;
+    // RFC 9110's grammar is `auth-scheme [ 1*SP token68 ]`, so more than one
+    // space is legal and the extra would otherwise fail the compare.
+    scheme
+        .eq_ignore_ascii_case("Bearer")
+        .then(|| token.trim_start_matches(' '))
+}
+
+/// Compares two secrets without leaking their contents through timing.
+pub fn secrets_match(left: &SecretString, right: &SecretString) -> bool {
+    constant_time_eq(
+        left.expose_secret().as_bytes(),
+        right.expose_secret().as_bytes(),
+    )
+}
+
+// ring deprecated its direct comparison helper; `hmac::verify` compares
+// tags in constant time, so equal inputs iff the tag over one verifies
+// against the other.
+/// Built once. The key material is empty and fixed, so rebuilding it per
+/// comparison only repeated the block-size padding work on the token path.
+static COMPARE_KEY: LazyLock<hmac::Key> = LazyLock::new(|| hmac::Key::new(hmac::HMAC_SHA256, &[]));

Review Comment:
   simplification: `subtle` is already in the workspace dependencies. `left.ct_eq(right).into()` replaces the two-hmac compare and `COMPARE_KEY`.



##########
core/connectors/sources/http_source/src/auth.rs:
##########
@@ -0,0 +1,267 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::sync::LazyLock;
+
+/// HMAC algorithms accepted for signature validation. SHA-256 covers GitHub,
+/// Stripe, and most modern providers; SHA-1 exists only for legacy senders.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

Review Comment:
   simplification: `HmacAlgorithm` mirrors two `EndpointAuthType` variants and the serde derives are never used. an `EndpointAuthType::ring_algorithm() -> Option<hmac::Algorithm>` removes the enum and the mapping.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    let presented = request_headers
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(strip_bearer)
+        .map(SecretString::from);
+    match presented {
+        Some(presented) if secrets_match(&presented, expected) => None,
+        _ => Some(error_response(StatusCode::UNAUTHORIZED, "unauthorized")),
+    }
+}
+
+fn is_usable(secret: &Option<SecretString>) -> bool {

Review Comment:
   simplification: same check as `validate()` in lib.rs. one shared helper.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1105 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+        submitted: false,
+    };
+
+    if !instance
+        .mutate_registry(|registry| registry.insert(endpoint))
+        .await
+    {
+        // 128 bits of entropy makes this unreachable in practice; refusing to
+        // overwrite is what keeps it from silently retargeting live traffic.
+        warn!(
+            "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+            instance_id = instance.id
+        );
+        return error_response(StatusCode::CONFLICT, "endpoint id collision");
+    }
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance
+            .mutate_registry(|registry| registry.remove(endpoint_id.as_str()))
+            .await
+        {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    // Restoring prefers TOML over any still-active persisted entry, so a
+    // rotated static secret would silently revert on the next restart and the
+    // operator would believe a leaked secret had been replaced.
+    if instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .is_some_and(|endpoint| endpoint.origin == EndpointOrigin::Static)
+    {
+        return error_response(
+            StatusCode::CONFLICT,
+            "a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance",
+        );
+    }
+
+    let rotated = instance
+        .mutate_registry(|registry| {
+            let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+                return false;
+            };
+            if !endpoint.is_active() {
+                return false;
+            }
+            endpoint.auth_secret = Some(request.auth_secret.clone());
+            endpoint.submitted = false;
+            true
+        })
+        .await;
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Option<Json<RevokeRequest>>,
+) -> Response {
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()))
+        .await;
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    let presented = request_headers
+        .get(header::AUTHORIZATION)

Review Comment:
   simplification: this is `validate_bearer(bearer_header(headers), expected)` written out by hand, with an extra `SecretString` allocation. reuse the helpers and make `strip_bearer` private.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5549879471

   /ready


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984822249


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;

Review Comment:
   Fixed in `fix(connectors): log why open failed, since the message goes nowhere else`.
   
   I verified the chain before changing anything rather than taking it from the description. `SourceContainer::open` ends `if result.is_ok() { 0 } else { 1 }`, so the payload is discarded and never logged, and `init_source` builds `"Plugin initialization failed (ID: {id})"` and puts that on `last_error`. Both exactly as you had them.
   
   `open` now logs whatever it is about to return, in one place rather than a line at each of the three failure points, so they cannot drift. That rescues all of `validate`'s messages, the field `join` names on a mismatch, a route conflict, and the refusal to serve an undecodable registry. Its body moved to `open_inner` to make the single call site possible.
   
   I checked your point about the callback instead of assuming it. `Registry::default().with(CallbackLayer::new(log_callback))` runs at the top of the shim, before `factory` and before `source.open()`, and a captured runtime log from the integration suite has this connector's own `info!` from inside `open()` in it, tagged `connector_target="iggy_connector_http_source"`. So a plugin-side line from that function does reach the operator. To be exact about what I observed: that was the success-path `info!`, not the new `error!`, but it is the same function on the same path.
   
   Two things fell out of the message becoming visible.
   
   It carried `InitError`'s prefix twice. `new` stored the restore failure as text and `open` wrapped that text in a second `InitError`, so it read "Init error: Init error: cannot decode...". Nobody had seen it because nothing read it. The field holds the error itself now, and a test pins the prefix count at one; restoring the old wrap turns it red.
   
   The doc cascade is the rest of it. The `last_error` claims in `state.rs`, two in `lib.rs`, the `restore_error` field comment and `README.md:264` all said the reason arrives on the control API, which is the claim this path could not honour. They now say the log carries it, and the README states the rule once as an operational note rather than five times.
   
   One I deliberately did not touch: `README.md:270`, on a failed state save showing as `last_error`. That is a different path, the forwarding loop calls `set_error` with a real message, so that claim is true and stays.
   
   I said earlier that one corner of this had landed with the state framing. It is folded in properly now: the `error!` I had put inside `restore` is gone, since `open` logs the same refusal and two lines for one failure is worse than none.
   
   203 unit tests, and all 6 http_source integration tests pass.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5630225601

   @numinnex I put the round 6 work through a two round adversarial review before asking you to look at it again. It found that the fixes themselves held up, and that several things I told you about them did not. Five corrections, all pushed.
   
   **1. My test for the state framing was vacuous.** I told you the fix was covered by a test that truncated a blob. Truncation was never the hole: I rebuilt the pre-frame shape against the pinned rmp-serde and every one of the 92 prefixes already failed on EOF, so that test passes at the parent commit and proved nothing. The shape that actually failed open is `[0x90]`, which decoded as a registry with no endpoints. That is what the test restores from now, against a TOML file still declaring the endpoint whose tombstone went missing. `test(connectors): test the state shapes that actually failed open`.
   
   The same review found what the trailing length check is really for, which I had not tested or described: rewriting the byte that opens the `state` map turns a tombstone back into an active endpoint and leaves the revocation bytes unread behind the frame. Arity, version and the count all pass it. That is a resurrected endpoint serving with its secret, and it now has a test.
   
   **2. I told you a `management_token` typo is logged nowhere. It is logged.** `management.rs` names that exact condition on every listener bind. I had checked with a grep that required the word and the log macro on one line, and the macro opens a line above the string, so my check could not have found it however wrong I was. The README says the opposite thing now.
   
   **3. My description of the readiness window was wrong twice.** There is no Iggy login in it; that happens once before any source is initialised. And the window is not one connector's producer setup: the runtime finishes the sources it has not reached yet, then every sink, in series, and only then starts any poll task. Which sources those are comes from an unordered map. You had told me the window spans other connectors and I dropped it.
   
   **4. The admin body limit did not cover every field cap, which was the whole claim.** The revoke reason was not in the sum. Registration is still the largest legal body, but by about 15%, not the margin I implied. Both fixed.
   
   **5. Answering 429 before reading the body costs the connection, and sometimes the answer.** Measured, not reasoned: hyper makes one drain attempt then closes the read half, at about 32 KiB of head plus body on a fresh connection and lower on a reused one. A sender that reads while writing usually still gets the 429. One that writes the whole body first can take a reset instead and never see it, which at the default 1 MiB cap is a real fraction of requests. The gate still does what you asked for, the upload really is cut off, and `Connection: close` was measured and does not help. This is now written next to the check rather than left for someone to discover.
   
   One more thing worth saying plainly. The second review round found that my fix for `server.rs:278` had introduced a regression: gating the management warning on "has this instance polled" removed a false alarm and the only signal for an instance that is wedged before its first poll, and the test I shipped alongside it asserted the resulting green health. Fixed in `fix(connectors): say when an instance has not started polling, rather than nothing`.
   
   212 unit tests and all 13 `connectors::http` integration tests pass. Nothing in the code changed direction as a result of the review; what changed is that the claims now match it.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984383368


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;

Review Comment:
   Accepted, and the doc cascade is the part that makes it worth doing properly rather than as a one line log fix.
   
   Not done yet, but one corner of it landed this session by accident. `fix(connectors): frame the state file so a short read cannot fail open` moved the state decode off the SDK helper, and that helper's `warn!` was the only thing logging why a registry was refused, so `restore` now logs the reason itself before returning the `Err`. That is your fix applied to exactly one call site because leaving it out would have been a regression. The other sites, the 16 `validate()` strings, `bind()`, `ensure_compatible`, `RouteConflict` and the restore refusal, are still dead text.
   
   Queued next, with the four doc claims at `state.rs:84`, `lib.rs:707-709` and `README.md:218-222,262` settled in the same change rather than separately.
   



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only
+                .store(state.is_some(), Ordering::Release);
+            state
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        self.last_batch_carried_state
+            .store(state.is_some(), Ordering::Release);
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued),
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free.
+    ///
+    /// A Nack does not mean neither happened. The runtime NACKs a batch it sent
+    /// successfully but whose state it could not persist, and the SDK NACKs on
+    /// its own result timeout while that send may still have landed. Holding
+    /// the copy and replaying it is therefore at-least-once by construction:
+    /// the alternative, dropping it, would turn every one of those into
+    /// silent loss.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.lock_staged().take();

Review Comment:
   Accepted. Resetting on `last_batch_carried_state` rather than on any Ack.
   
   The part I had not seen is that this bites the default File backend, not just HTTP. `is_latched` returning `false` unconditionally for `File` means a read-only mount or ENOSPC gives exactly the alternating pattern you describe, so `consecutive_nacks` never reaches the stop and it is one failed write per poll forever.
   
   Queued with `lib.rs:954`, since they are the same state machine and I would rather review the two together than land one and re-derive the other.
   



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            // The same rule the management API applies, minus the checks that
+            // only make sense when an endpoint is being created. Written out
+            // here once, the two lists drifted: config admitted an
+            // `auth_type: none` carrying a secret, which then rode into the
+            // state file in clear where nothing reads it.
+            //
+            // `Existing`, so a TOML `expires_at` that has passed is still
+            // admitted. `validate()` runs inside `open()`, and refusing there
+            // would take the whole instance down on the first restart after
+            // that timestamp; the endpoint answers 404 on its own path instead.
+            //
+            // Prefix only in the message: this becomes `last_error`, which the
+            // runtime logs and serves over its control API, and the operator
+            // fixes the endpoint while keeping the id.
+            if let Err(reason) = admit_endpoint(
+                endpoint.auth_type,
+                &endpoint.auth_secret,
+                &endpoint.hmac_header,
+                &endpoint.hmac_prefix,
+                endpoint.expires_at,
+                Admission::Existing,
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {}: {reason}",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            departed: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_batch_carried_state: AtomicBool::new(false),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Only a batch that actually carried state may re-arm. Re-arming
+            // unconditionally set the dirty bit with no pending change behind
+            // it, and `close()` then reported "0 change(s) not submitted" - a
+            // data-loss alarm on the one field the README tells operators to
+            // trust, raised for a flush that was never owed. It also spent the
+            // backoff budget on NACKs that had nothing to do with the state
+            // store. An empty batch that carried nothing needs no re-arm: if
+            // `take_dirty_state` declined because the writer gate was
+            // contended, it re-posted the permit itself, and if nothing was
+            // dirty there is nothing to retry.
+            if !self.last_batch_carried_state.load(Ordering::Acquire) {
+                return Ok(());
+            }
+            // `take_dirty_state` already cleared the flag, so re-arming here is
+            // the only thing that stops a revocation being lost while the API
+            // reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();
+            warn!(
+                "Runtime NACKed the state flush for {CONNECTOR_NAME} connector ID: {}, re-arming it",
+                self.shared.id
+            );
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}",
+            self.shared.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        if let Some(error) = self.restore_error.take() {
+            return Err(Error::InitError(error));
+        }
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        self.shared.log_auth_posture();
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.shared.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        let _polling = self.shared.enter_poll();
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch() {
+            // Unreachable as written: only an empty batch carries state, an
+            // empty batch stages nothing, so no replay can follow one and the
+            // marker is already false here. Written anyway so the invariant is
+            // local to `poll()` rather than resting on that argument holding
+            // for every future caller of `stage`.
+            self.last_batch_carried_state
+                .store(false, Ordering::Release);
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        // Empty until traffic actually arrives. Reserving up front cost a
+        // `max_batch_size` allocation on every flush-only and idle poll, which
+        // at the configurable ceiling is megabytes allocated and freed to carry
+        // nothing.
+        let mut queued: Vec<QueuedMessage> = Vec::new();
+        let receiver = self.receiver.lock().await;
+        // Ordered, not raced. Left unbiased, an armed flush and waiting traffic
+        // were a coin flip, so a mutation took two polls to leave on average and
+        // on a quiet gateway a poll is however long the next request takes.
+        //
+        // The order flips after a state-only batch, which is the guard that
+        // makes biasing safe: pinned with the flush first, a caller looping on
+        // the management API re-arms the notify faster than the bridge drains
+        // and `recv()` never runs. Both arms stay live in either order, so a
+        // flush on an idle bridge still has its wakeup; only first refusal
+        // moves. Reading it clears it, so the flip lasts exactly one poll.
+        let traffic_first = self.last_poll_was_state_only.swap(false, Ordering::AcqRel);
+        if traffic_first {
+            tokio::select! {
+                biased;
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+                _ = self.shared.state_flush.notified() => {}
+            }
+        } else {
+            tokio::select! {
+                biased;
+                _ = self.shared.state_flush.notified() => {}
+                received = receiver.recv() => drain_bridge(&receiver, received, max_batch_size, &mut queued),
+            }
+        }
+
+        // State rides an empty batch and nothing else, so no failed publish
+        // can skip its save. Under traffic that means deferring to a later
+        // poll; re-arming the notify stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            let state = self.shared.take_dirty_state();
+            // Only a batch that carried state counts: an empty poll that found
+            // nothing to flush has not taken a turn away from traffic.
+            self.last_poll_was_state_only

Review Comment:
   Accepted. Flipping when the flush arm wins rather than when it produced state.
   
   The reachability argument is the part that makes this more than theoretical: `try_lock` losing to an ordinary `try_mutate_registry` needs no panic and no poisoning, and the decline arm re-posting the permit is what turns it into a loop rather than a single miss.
   
   Queued with `lib.rs:987` as one change over the same machine.
   



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)

Review Comment:
   Accepted, and this is the one I most want to get right rather than fast, so it is last of the seven I have left.
   
   Publishing on the first `poll()` instead of in `join()` is the fix I will write. I take the point that a boot grace period is not an alternative: answering 200 while nothing drains the bridge is a worse failure than the one it papers over, because it is silent.
   
   What makes it the largest change here is that it moves where routes become visible, which touches the readiness rules and the handover cases the two POST handlers already re-resolve against. I would rather do it on its own than fold it into a batch.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984384431


##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)
+            && !self.instances.is_empty()
+            && self
+                .instances
+                .iter()
+                .all(|instance| instance.poll_is_live(now_seconds))
+    }
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        // Without these, a mistyped path got axum's empty-bodied 404 and a
+        // wrong method an undocumented 405, while every other response on this
+        // listener carries `{"error": ...}`. A sender parsing that field broke
+        // on exactly the two responses a misconfiguration produces.
+        //
+        // The admin listener deliberately keeps axum's bare fallback: an
+        // unconfigured management API is not mounted at all there, and
+        // answering with this crate's error shape would make "no token
+        // configured" look like a route that exists and refused.
+        .fallback(|| async { error_response(StatusCode::NOT_FOUND, "not found") })
+        .method_not_allowed_fallback(|| async {
+            error_response(StatusCode::METHOD_NOT_ALLOWED, "method not allowed")
+        })
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))

Review Comment:
   Accepted. The admin limit gets its own const sized off the field caps at `auth.rs:62-64`.
   
   The consequence you name is the one that decides it: what a small webhook cap blocks is incident-time secret rotation, and `ensure_compatible` refuses a join that disagrees on `max_body_size_bytes`, so it cannot be raised for one instance to get out of that. Answering `{"error":"invalid request body"}` with no field and no cause makes it worse.
   
   Queued.
   



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let now_seconds = unix_now_seconds();
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // The same rule registration applies, asked here and only warned
+            // about. `restore` failing is a hard `open()` failure, so refusing
+            // would take a whole instance down over one stored value an
+            // operator cannot edit without the state file.
+            //
+            // Asked rather than re-derived, because the two hand-written checks
+            // that used to live here had already drifted from it: they covered
+            // the ceilings and a malformed `hmac_header`, and silently skipped
+            // an endpoint advertising auth with no usable secret. That one
+            // restores active, reads active on the admin API, and rejects every
+            // request forever, which is fail-closed and completely silent.
+            //
+            // `Existing`, so a stored `expires_at` that has merely passed is not
+            // reported as a fault: the endpoint answers 404 on its own path and
+            // that is the documented behaviour.
+            //
+            // Skipped for an endpoint whose expiry has already passed. Its
+            // secret is cleared below, so on the next restart this rule would
+            // report `MissingSecret` and blame the credential for a refusal
+            // that expiry already explains.
+            if !revoked
+                && !endpoint.is_expired(now_seconds)
+                && let Err(reason) = admit_endpoint(
+                    endpoint.auth_type,
+                    &endpoint.auth_secret,
+                    &endpoint.hmac_header,
+                    &endpoint.hmac_prefix,
+                    endpoint.expires_at,
+                    Admission::Existing,
+                )
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id}: {reason}; it is served but every request to it will be refused until it is re-registered",
+                    endpoint_id.log_prefix()
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    // The map was seeded from TOML, so Occupied means TOML
+                    // still declares this id: the tombstone is static whatever
+                    // the state file says. Taking the persisted `origin`
+                    // verbatim let a `Dynamic` tombstone be the entry that
+                    // outranks a live TOML block, and `reclaimable_tombstones`
+                    // evicts exactly the dynamic ones, so the next restart
+                    // served that endpoint and its secret again. Reclamation is
+                    // only safe because a static tombstone is never eligible.
+                    endpoint.origin = EndpointOrigin::Static;
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    // A static entry reaches this arm only when TOML no longer
+                    // declares it. Restoring an active one resurrects an
+                    // endpoint the operator decommissioned by deleting it, and
+                    // `rotate_secret` then refuses it as static and points at a
+                    // TOML entry that is gone, so there is no way back. Its
+                    // tombstone still has to survive: re-adding the id to TOML
+                    // later must not undo a revocation.
+                    if !revoked && endpoint.origin == EndpointOrigin::Static {
+                        dropped_static += 1;
+                        continue;
+                    }
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        // Same reasoning as `revoke()`: the handler answers 404 on an expired
+        // endpoint before `authorize()` runs, so its stored secret is already
+        // dead weight, and nothing compacts the registry. Keeping it wrote a
+        // credential the operator can no longer use back to disk on every later
+        // flush, indefinitely, which is exactly what `revoke()` clears the
+        // secret to avoid.
+        //
+        // The endpoint keeps its slot and stays `Active`. Reclaiming it would
+        // make endpoints disappear on a clock condition rather than an operator
+        // action.
+        //
+        // Restore only, deliberately. An endpoint that expires while the
+        // instance is running keeps its stored secret until the next restart,
+        // because clearing it then would need a clock-driven sweep mutating the
+        // registry from `poll()`. `revoke` is what clears it immediately.
+        let mut expired_secrets = 0;
+        for endpoint in endpoints.values_mut() {
+            if endpoint.is_active()
+                && endpoint.is_expired(now_seconds)
+                && endpoint.auth_secret.is_some()
+            {
+                endpoint.auth_secret = None;
+                expired_secrets += 1;
+            }
+        }
+        // The third of the three restore-time faults that get a line of their
+        // own: an expired endpoint is otherwise silent at startup.
+        if expired_secrets > 0 {
+            warn!(
+                "Cleared the stored secret of {expired_secrets} expired endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id}; they keep their slot and answer 404 until re-registered"
+            );
+        }
+
+        // Loud on purpose: these were serving before the restart, and the only
+        // trace of them left is this line.
+        if dropped_static > 0 {
+            warn!(
+                "Dropped {dropped_static} persisted static endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id} that the TOML config no longer declares; they no longer serve"
+            );
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"
+        );
+
+        Ok(EndpointRegistry { endpoints })
+    }
+
+    pub fn endpoints(&self) -> impl Iterator<Item = &Endpoint> {
+        self.endpoints.values()
+    }
+
+    pub fn endpoint(&self, endpoint_id: &str) -> Option<&Endpoint> {
+        self.endpoints.get(endpoint_id)
+    }
+
+    pub fn endpoint_mut(&mut self, endpoint_id: &str) -> Option<&mut Endpoint> {
+        self.endpoints.get_mut(endpoint_id)
+    }
+
+    /// [`Self::try_insert`] for tests that only care whether the registry
+    /// changed.
+    ///
+    /// Test-only on purpose. It collapses `Full` and `Collision` into one
+    /// `false`, so production code reaching for it would drop the distinction
+    /// between a registry at its ceiling and an id that is already taken, and
+    /// answer the caller the same way for both.
+    #[cfg(test)]
+    pub fn insert(&mut self, endpoint: Endpoint) -> bool {
+        self.try_insert(endpoint) == InsertOutcome::Inserted
+    }
+
+    /// Registers a new endpoint, reporting why it was refused.
+    ///
+    /// Nothing evicts tombstones on its own and every mutation clones the whole
+    /// registry, so without a ceiling a caller holding the management token can
+    /// grow the state file and the per-mutation cost without limit. At the
+    /// ceiling the oldest revoked *dynamic* entries are reclaimed first: such an
+    /// endpoint exists only here, so dropping it leaves its path answering 404
+    /// exactly as its tombstone did. A revoked static one is never reclaimed,
+    /// because its tombstone is what outranks a TOML entry that still declares
+    /// it.
+    ///
+    /// Either the whole thing succeeds or nothing is touched, so a refusal
+    /// cannot leave the registry partially reclaimed and arm a flush for it.
+    pub fn try_insert(&mut self, endpoint: Endpoint) -> InsertOutcome {
+        if self.endpoints.contains_key(&endpoint.endpoint_id) {
+            return InsertOutcome::Collision;
+        }
+        if self.endpoints.len() >= MAX_ENDPOINTS {
+            let wanted = self.endpoints.len() - MAX_ENDPOINTS + 1;

Review Comment:
   Accepted, and I have deliberately kept a door open for it.
   
   `fix(connectors): frame the state file so a short read cannot fail open` added a declared endpoint count to the state frame, and I did not bound it by `MAX_ENDPOINTS` there on purpose, because you asked for a warn in `restore` rather than a refusal and a hard cap in the decode would have contradicted that.
   
   So the shape stays as you wrote it: reject `config.endpoints.len() > MAX_ENDPOINTS` in `validate`, warn rather than fail in `restore`, and report the real length in the 507 at `management.rs:206`. Queued.
   



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2271 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::{Admission, admit_endpoint};
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the batch the last `poll()` returned carried registry state.
+    ///
+    /// Read by `on_nack`, which may only re-arm a flush for a batch that was
+    /// actually carrying one. Written on every exit of `poll()`.
+    last_batch_carried_state: AtomicBool,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// What a validated mutation did.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOutcome {
+    /// Published, flush armed, change counted.
+    Applied,
+    /// The mutation itself declined; nothing was a change to begin with.
+    NoChange,
+    /// The candidate failed validation, so nothing was published or armed.
+    Rejected,
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// Set by `leave()` before it counts what the bridge still holds.
+    ///
+    /// The re-resolve in the request path narrows the window where a handler
+    /// enqueues into a departing instance, but does not close it: the gate
+    /// passes, and `enqueue` then checks `is_full`, builds the header map and
+    /// copies the body before `try_send`, all of which `leave()` can overtake.
+    /// A message landing after its count is never drained and the sender was
+    /// told 200. Checked after `try_send` so that answer becomes a 503 instead.
+    departed: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub(crate) fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub(crate) fn mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+    ) -> bool {
+        self.try_mutate_registry(mutation, |_| true) == MutationOutcome::Applied
+    }
+
+    /// A mutation that must prove itself before it becomes visible.
+    ///
+    /// `validate` sees the candidate registry while it is still private to this
+    /// call. Rejecting there publishes nothing, arms no flush and counts no
+    /// pending change, which is what the register path needs: publishing first
+    /// and undoing on failure cannot be made correct, because the same call
+    /// arms the flush, so the runtime may already have persisted a change the
+    /// caller is about to be told failed, and an insert that reclaimed
+    /// tombstones to make room does not get them back.
+    ///
+    /// `validate` must stay synchronous. It runs under `registry_writer`, and
+    /// an await there would put a `std::sync::Mutex` across it and make
+    /// `take_dirty_state`'s `try_lock` fail for the duration, silently skipping
+    /// flushes.
+    pub(crate) fn try_mutate_registry(
+        &self,
+        mutation: impl FnOnce(&mut EndpointRegistry) -> bool,
+        validate: impl FnOnce(&EndpointRegistry) -> bool,
+    ) -> MutationOutcome {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return MutationOutcome::NoChange;
+            }
+            if !validate(&next) {
+                return MutationOutcome::Rejected;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        MutationOutcome::Applied
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    /// Marks the instance as having left the route table, before anything
+    /// counts what its bridge still holds.
+    pub(crate) fn mark_departed(&self) {
+        self.departed.store(true, Ordering::Release);
+    }
+
+    pub(crate) fn has_departed(&self) -> bool {
+        self.departed.load(Ordering::Acquire)
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,

Review Comment:
   Accepted. An Options row saying unknown `plugin_config` keys are ignored, plus an operational note to grep the open log for "with NO authentication".
   
   Agreed that `deny_unknown_fields` is not the answer here, for the reason you give: the runtime's env overrides arrive as flat keys, so the silence is by design and turning it into an error would break a documented path.
   
   Queued. It is a documentation change, so it will not be batched with a code fix.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio merged PR #3798:
URL: https://github.com/apache/iggy/pull/3798


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5310445380

   This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs.
   
   If you need a review, please ensure CI is green and the PR is rebased on the latest master. Don't hesitate to ping the maintainers - either `@core` on Discord or by mentioning them directly here on the PR.
   
   Thank you for your contribution!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3847134824


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {

Review Comment:
   a typo in `auth_bearer_token` leaves `POST /topics/{topic_path}` completely unauthenticated, because the handler skips the whole auth block when it is `None`, and nothing logs it. a typo'd `expires_at` just never expires.
   
   `deny_unknown_fields` is not the fix here: the runtime's env overrides arrive as flat lowercase keys like `endpoints_0_auth_secret`, so it would turn every override into an `open()` failure. a `warn!` in `open()` naming the auth posture of each path being served would cover it, the way the management api already logs whether it is mounted. on the request body structs in management.rs it is safe.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,545 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::ConnectorState;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Self {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {

Review Comment:
   this turns a deliberate fail-closed decode into a fail-open restore. `auth_type` and `state` have no `#[serde(default)]` on purpose so a short record fails the decode rather than resurrecting a revoked endpoint - and then any decode failure here throws the whole registry away, serves TOML instead, and loses every tombstone while the connector keeps running. the doc comment on `Endpoint` describes this exact outcome.
   
   fix: fail `open()` instead of warning. that surfaces as `last_error` on the control api, which is the only way an operator finds out the tombstones are gone. the guard test passes `&[]` as static config, so it never covers the case that matters.



##########
core/connectors/sources/http_source/src/routes.rs:
##########
@@ -0,0 +1,422 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Route table for a shared listener.
+//!
+//! Every instance joining a listener contributes its named topic path and its
+//! secret-path endpoints. The merged table is rebuilt and swapped whole on
+//! join, leave, and management mutations, so a request resolves its auth
+//! requirements and its destination bridge from a single atomic load.
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::fmt::{self, Display, Formatter};
+use std::sync::Arc;
+
+use crate::types::EndpointId;
+use crate::{EndpointAuthType, SharedState, StaticEndpointConfig};
+
+/// Lifecycle state of a secret-path endpoint.
+///
+/// Revocation writes a tombstone rather than deleting the entry: the tombstone
+/// persists through a restart, so a stale TOML entry can never resurrect an
+/// endpoint an operator revoked.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointState {
+    Active,
+    Revoked { reason: String, revoked_at: u64 },
+}
+
+/// Where an endpoint came from, which decides whether a TOML edit plus an
+/// instance restart or a management API call is the way to change it.
+#[derive(Debug, Clone, Copy, Default, Hash, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointOrigin {
+    #[default]
+    Static,
+    Dynamic,
+}
+
+/// A secret-path endpoint served at `POST /e/{endpoint_id}`.
+///
+/// Persisted verbatim into the runtime state directory, HMAC and bearer
+/// secrets included, so endpoints created through the management API survive a
+/// restart. That file is as sensitive as the TOML it mirrors, which is why the
+/// README requires `chmod 700` on the state path.
+/// Fields added after the first release must be APPENDED and carry
+/// `#[serde(default)]`. `ConnectorState` uses rmp's compact codec, where a
+/// struct is a positional array, so a new field without a default makes every
+/// existing state file fail to decode, and `EndpointRegistry::restore` turns a
+/// decode failure into "tombstones lost, revoked endpoints served again".
+///
+/// `auth_type` and `state` deliberately have no default: for those two, a
+/// missing element must fail the decode rather than read as an active,
+/// unauthenticated endpoint.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Endpoint {
+    pub endpoint_id: EndpointId,
+    // No default: an absent auth_type must fail the decode, not silently
+    // read as `None` and drop the second factor.
+    pub auth_type: EndpointAuthType,
+    #[serde(default, serialize_with = "crate::state::serialize_secret_to_state")]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default)]
+    pub hmac_header: String,
+    #[serde(default)]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+    #[serde(default)]
+    pub origin: EndpointOrigin,
+    // No default: `EndpointState::default()` would be `Active`, so a record
+    // short by one element would resurrect a revoked endpoint - turning a
+    // loud decode failure into a silent, fail-open one.
+    pub state: EndpointState,
+    /// Whether this endpoint has been handed to the runtime for persistence.
+    /// Reset on every mutation, never itself persisted: a restored endpoint is
+    /// durable by definition. Not named `persisted`, because the plugin gets
+    /// no acknowledgement that the runtime's write actually landed.
+    #[serde(skip)]
+    pub submitted: bool,
+}
+
+impl Endpoint {
+    pub fn is_active(&self) -> bool {
+        matches!(self.state, EndpointState::Active)
+    }
+
+    /// Whether a request arriving now would be accepted.
+    pub fn is_serving(&self, now_seconds: u64) -> bool {
+        self.is_active() && !self.is_expired(now_seconds)
+    }
+
+    pub fn is_expired(&self, now_seconds: u64) -> bool {
+        self.expires_at
+            .is_some_and(|expires_at| now_seconds >= expires_at)
+    }
+
+    pub fn revoke(&mut self, reason: String, revoked_at: u64) {

Review Comment:
   revoke leaves `auth_secret` populated and the serializer writes it into the state file in the clear. it is dead weight anyway - the handler 404s on `Revoked` before `authorize()` runs - and nothing ever compacts tombstones, so revoking because a secret leaked keeps the leaked secret on disk indefinitely. clear it here.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,545 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::ConnectorState;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, StaticEndpointConfig};
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Self {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints

Review Comment:
   a duplicate `endpoint_id` inside one instance's TOML silently last-wins here, and `validate()` does not check for it. `RouteTable::build` walks the already-deduped map, so it cannot catch it either. `static_count` below is measured after the dedup, so even the restore log reports the collapsed number. a copy-pasted block whose second copy carries a weaker `auth_type` wins.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {
+            return Err(Error::InvalidConfigValue(
+                "buffer_capacity must be at least 1".to_string(),
+            ));
+        }
+        if self.max_batch_size == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_batch_size must be at least 1".to_string(),
+            ));
+        }
+        if self.max_body_size_bytes == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_body_size_bytes must be at least 1".to_string(),
+            ));
+        }
+        if let Some(instance_name) = &self.instance_name
+            && HeaderKey::try_from(instance_name.as_str()).is_err()
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+            )));
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        for endpoint in &self.endpoints {
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        let registry = EndpointRegistry::restore(&config.endpoints, state, id);
+        let (sender, receiver) = crossfire::mpsc::bounded_async(config.buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: Mutex::new(None),
+        }
+    }
+
+    pub fn shared(&self) -> &Arc<SharedState> {
+        &self.shared
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    async fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.staged.lock().await;
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    async fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.staged.lock().await = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.

Review Comment:
   this covers decode but not encode. with `schema = "json"` the runtime's encoder rejects a raw payload, that counts into `processing_errors`, and a non-zero count becomes an `Err` - so it is a NACK, not a drop. the batch then replays forever and the SDK stops the poll task after five NACKs while the listener still answers 200.
   
   README line 98 says the batch is dropped, same mistake. worth rejecting a non-`raw` schema in `open()`, since it is the one config value that can wedge the connector with no way out.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1659 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::ArcSwap;
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+pub async fn leave(instance: &Arc<SharedState>) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let remaining: Vec<Arc<SharedState>> = server
+        .state
+        .instances()
+        .into_iter()
+        .filter(|joined| joined.id != instance.id)
+        .collect();
+    let remaining_count = remaining.len();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    server
+        .state
+        .metrics
+        .forget_instance(&instance.instance_name);
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    routes: ArcSwap<RouteTable>,
+    instances: ArcSwap<Vec<Arc<SharedState>>>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            routes: ArcSwap::from_pointee(RouteTable::default()),
+            instances: ArcSwap::from_pointee(Vec::new()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        (**self.instances.load()).clone()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.instances
+            .load()
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.routes.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.secret_path_count(),
+            dropped.named_path_count(),
+            self.instances.load().len()
+        );
+        self.routes.store(Arc::new(RouteTable::default()));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let table = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.instances.store(Arc::new(instances));
+        self.routes.store(Arc::new(table));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone()),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {

Review Comment:
   `listen_addr` cannot be compared here since it is the map key, but README line 191 says it is validated. that is not only a doc bug: when `admin_listen_addr` differs too, both binds succeed and you end up with two independent listeners and no error at all, each seeing only its own instances - so the `instance_name` and path uniqueness checks are both bypassed. `0.0.0.0:9090` and `127.0.0.1:9090` are different keys, so a spelling difference is enough. when only `listen_addr` differs, the operator gets an "address already in use" naming the admin port, which is the field that is fine.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,931 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference.
+
+use axum::extract::{Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{secrets_match, strip_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, error_response, refresh_routes};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    request_headers: HeaderMap,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,

Review Comment:
   axum runs every extractor before the handler body, so this reads and parses the request body before `denied()` gets a look. the test at the bottom of this file asserts each route refuses a wrong token before it does anything else, which is not what happens. the admin router also carries no `DefaultBodyLimit`, so the cap here is axum's 2 MiB default rather than `max_body_size_bytes`. `rotate_secret` has the same shape.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {
+            return Err(Error::InvalidConfigValue(
+                "buffer_capacity must be at least 1".to_string(),
+            ));
+        }
+        if self.max_batch_size == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_batch_size must be at least 1".to_string(),
+            ));
+        }
+        if self.max_body_size_bytes == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_body_size_bytes must be at least 1".to_string(),
+            ));
+        }
+        if let Some(instance_name) = &self.instance_name
+            && HeaderKey::try_from(instance_name.as_str()).is_err()
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+            )));
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        for endpoint in &self.endpoints {
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        let registry = EndpointRegistry::restore(&config.endpoints, state, id);
+        let (sender, receiver) = crossfire::mpsc::bounded_async(config.buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: Mutex::new(None),
+        }
+    }
+
+    pub fn shared(&self) -> &Arc<SharedState> {
+        &self.shared
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    async fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.staged.lock().await;
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    async fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.staged.lock().await = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    async fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.staged.lock().await;
+        let Some(batch) = staged.as_mut() else {
+            return Ok(());
+        };
+        batch.nacks += 1;
+        let nacks = batch.nacks;
+        let count = batch.messages.len();
+        drop(staged);
+        warn!(
+            "Runtime NACKed {count} messages ({nacks} so far) for {CONNECTOR_NAME} connector ID: {}, replaying them on the next poll",
+            self.id
+        );
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Source for HttpSource {
+    async fn open(&mut self) -> Result<(), Error> {
+        self.shared.config.validate()?;
+        server::join(Arc::clone(&self.shared)).await?;
+        info!(
+            "Opened {CONNECTOR_NAME} connector ID: {}, listen address: {}, endpoints: {}, named path: {:?}",
+            self.id,
+            self.shared.config.listen_addr,
+            self.shared.registry().serving_count(unix_now_seconds()),
+            self.shared.config.topic_path,
+        );
+        Ok(())
+    }
+
+    async fn poll(&self) -> Result<ProducedMessages, Error> {
+        // An unacknowledged batch outranks new traffic: replaying it in order
+        // is what turns the runtime's NACK into a retry instead of a gap.
+        if let Some(staged) = self.staged_batch().await {
+            return Ok(staged);
+        }
+
+        let max_batch_size = self.shared.config.max_batch_size;
+        let mut queued: Vec<QueuedMessage> = Vec::with_capacity(max_batch_size);
+        let receiver = self.receiver.lock().await;
+        tokio::select! {
+            // The SDK races poll() against its own shutdown watch, so blocking
+            // here until traffic arrives is what keeps an idle gateway off the
+            // CPU. crossfire documents recv() as cancellation-safe.
+            received = receiver.recv() => match received {
+                Ok(message) => {
+                    queued.push(message);
+                    while queued.len() < max_batch_size {
+                        let Ok(message) = receiver.try_recv() else {
+                            break;
+                        };
+                        queued.push(message);
+                    }
+                }
+                // Reachable only once every sender is gone. Idle rather than
+                // spin the SDK's poll loop.
+                Err(_) => tokio::time::sleep(IDLE_POLL_INTERVAL).await,
+            },
+            _ = self.shared.state_flush.notified() => {}
+        }
+
+        if !queued.is_empty() {
+            let count = queued.len();
+            if self.shared.config.verbose_logging.unwrap_or(false) {
+                info!(
+                    "Polled {count} messages for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                debug!(
+                    "Polled {count} messages for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            }
+        }
+
+        // State rides an empty batch and nothing else, so the send it depends
+        // on cannot fail. Under traffic that means deferring to a later poll;
+        // re-arming the notify is what stops it waiting on traffic to arrive.
+        let state = if queued.is_empty() {
+            self.shared.take_dirty_state()
+        } else {
+            if self.shared.has_pending_state() {
+                self.shared.state_flush.notify_one();
+            }
+            None
+        };
+
+        Ok(ProducedMessages {
+            schema: Schema::Raw,
+            messages: self.stage(queued).await,
+            state,
+        })
+    }
+
+    /// Applies the runtime's verdict on the batch `poll()` last produced.
+    ///
+    /// An Ack means the batch reached the topic and its state was persisted, so
+    /// the staged copy is free. A Nack means neither happened, so the copy has
+    /// to outlive it for the next `poll()` to replay.
+    async fn on_batch_result(&self, result: source::SourceBatchResult) -> Result<(), Error> {
+        match result {
+            source::SourceBatchResult::Ack => {
+                self.staged.lock().await.take();
+                Ok(())
+            }
+            source::SourceBatchResult::Nack => self.on_nack().await,
+        }
+    }
+
+    async fn close(&mut self) -> Result<(), Error> {
+        // The SDK stops the poll task before calling this, so anything still
+        // in the bridge is already unreachable. Deregistering first is what
+        // stops new requests from being accepted into a queue nobody drains.
+        server::leave(&self.shared).await;
+        // A staged batch was NACKed on the way down and has no reader left.
+        // Name the loss instead of letting it disappear with the instance.
+        if let Some(staged) = self.staged.lock().await.take() {

Review Comment:
   `leave()` folds `sender.len()` into `http_source_dropped_on_close_total`, but this staged batch only gets a log line. so shutdown loss is under-reported by up to `max_batch_size` while README line 15 says the metric covers it. count it before `leave()` tears the registry down.



##########
core/integration/tests/connectors/http/http_source.rs:
##########
@@ -0,0 +1,496 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use super::{POLL_ATTEMPTS, POLL_INTERVAL_MS};
+use crate::connectors::fixtures::{
+    GITHUB_ENDPOINT_ID, GITHUB_HMAC_HEADER, GITHUB_INSTANCE, HttpSourceFixture, MANAGEMENT_TOKEN,
+    PARTNER_BEARER_TOKEN, PARTNER_ENDPOINT_ID, PARTNER_INSTANCE,
+};
+use iggy::prelude::IggyClient;
+use iggy_common::MessageClient;
+use iggy_common::{Consumer, Identifier, PollingStrategy};
+use iggy_connector_sdk::api::{ConnectorStatus, SourceInfoResponse};
+use integration::harness::seeds;
+use integration::iggy_harness;
+use reqwest::{Client, StatusCode};
+use serde_json::{Value, json};
+use std::time::Duration;
+use tokio::time::sleep;
+
+const API_KEY: &str = "test-api-key";
+const RESTORED_TOKEN: &str = "token-that-must-survive-a-restart";
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn webhook_post_produces_message_to_iggy(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push","repository":"apache/iggy"}"#;
+    let response = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .header("X-GitHub-Delivery", "72d3162e-cc78-11e3-81ab-4c9367dc0958")
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST the webhook");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_1", 1).await;
+    assert_eq!(
+        String::from_utf8_lossy(&messages[0].0),
+        body,
+        "the raw request body must reach Iggy byte for byte"
+    );
+    let headers = messages[0]
+        .1
+        .as_ref()
+        .expect("HTTP metadata forwarding is enabled");
+    assert_eq!(
+        header_value(headers, "iggy_source_instance").as_deref(),
+        Some(GITHUB_INSTANCE)
+    );
+    assert_eq!(
+        header_value(headers, "X-GitHub-Delivery").as_deref(),
+        Some("72d3162e-cc78-11e3-81ab-4c9367dc0958"),
+        "the delivery id is the consumer's dedup key and must survive the FFI hop"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn two_instances_share_one_listener(harness: &TestHarness, fixture: HttpSourceFixture) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let github_body = r#"{"from":"github"}"#;
+    let github = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(github_body.as_bytes()),
+        )
+        .body(github_body)
+        .send()
+        .await
+        .expect("Failed to POST to the GitHub endpoint");
+    let partner_body = r#"{"from":"partner"}"#;
+    let partner = http
+        .post(fixture.webhook_url(PARTNER_ENDPOINT_ID))
+        .header("Authorization", format!("Bearer {PARTNER_BEARER_TOKEN}"))
+        .body(partner_body)
+        .send()
+        .await
+        .expect("Failed to POST to the partner endpoint");
+
+    assert_eq!(github.status(), StatusCode::OK);
+    assert_eq!(
+        partner.status(),
+        StatusCode::OK,
+        "the second instance must be reachable on the port the first one bound"
+    );
+
+    let first = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_2a", 1).await;
+    let second = poll_payloads(&client, seeds::names::TOPIC_2, "http_source_cg_2b", 1).await;
+    assert_eq!(String::from_utf8_lossy(&first[0].0), github_body);
+    assert_eq!(
+        String::from_utf8_lossy(&second[0].0),
+        partner_body,
+        "one listener, but each instance produces to its own topic"
+    );
+    assert_eq!(
+        header_value(
+            second[0].1.as_ref().expect("metadata is on by default"),
+            "iggy_source_instance"
+        )
+        .as_deref(),
+        Some(PARTNER_INSTANCE)
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn management_registered_endpoint_accepts_until_revoked(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let client = harness.root_client().await.unwrap();
+    let http = webhook_client();
+    wait_for_gateway(&http, &fixture).await;
+
+    let endpoint_id = register_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    let body = r#"{"event":"dynamic"}"#;
+    let accepted = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the registered endpoint");
+    assert_eq!(
+        accepted.status(),
+        StatusCode::OK,
+        "an endpoint registered through the API must serve without a restart"
+    );
+
+    let messages = poll_payloads(&client, seeds::names::TOPIC, "http_source_cg_3", 1).await;
+    assert_eq!(String::from_utf8_lossy(&messages[0].0), body);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{endpoint_id}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the endpoint");
+    assert_eq!(revoked.status(), StatusCode::NO_CONTENT);
+
+    let after = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST to the revoked endpoint");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "a revocation must take effect immediately, and must not leak that the URL once worked"
+    );
+}
+
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn dynamic_endpoint_survives_connector_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    // Registered with a secret so the restart proves the credential survives
+    // the state round trip, not merely the endpoint id.
+    let endpoint_id = register_secured_endpoint(&http, &fixture, GITHUB_INSTANCE).await;
+    // The registry only reaches the runtime once a poll carrying it has been
+    // sent, so wait for the connector to report it submitted before pulling
+    // the rug out from under it.
+    wait_for_submitted(&http, &fixture, &endpoint_id).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(
+        restarted.status().is_success(),
+        "Restart request failed: {}",
+        restarted.status()
+    );
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let authorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .header("Authorization", format!("Bearer {RESTORED_TOKEN}"))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    let unauthorized = http
+        .post(fixture.webhook_url(&endpoint_id))
+        .body(r#"{"event":"after-restart"}"#)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+
+    assert_eq!(
+        authorized.status(),
+        StatusCode::OK,
+        "an endpoint that only ever existed in ConnectorState must come back with the connector"
+    );
+    assert_eq!(
+        unauthorized.status(),
+        StatusCode::UNAUTHORIZED,
+        "and its secret must come back with it, not be dropped to an open endpoint"
+    );
+}
+
+/// The README's strongest security claim: a revoked endpoint must not be
+/// resurrected by a restart that re-reads the TOML still declaring it.
+#[iggy_harness(
+    server(connectors_runtime(config_path = "tests/connectors/http/source.toml")),
+    seed = seeds::connector_multi_topic_stream
+)]
+async fn revoked_static_endpoint_stays_revoked_across_restart(
+    harness: &TestHarness,
+    fixture: HttpSourceFixture,
+) {
+    let http = webhook_client();
+    let api_url = harness
+        .connectors_runtime()
+        .expect("connector runtime should be available")
+        .http_url();
+    wait_for_gateway(&http, &fixture).await;
+
+    let body = r#"{"event":"push"}"#;
+    let before = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST before revocation");
+    assert_eq!(before.status(), StatusCode::OK);
+
+    let revoked = http
+        .delete(format!(
+            "{}/admin/endpoints/{GITHUB_ENDPOINT_ID}",
+            fixture.admin_url()
+        ))
+        .header("Authorization", format!("Bearer {MANAGEMENT_TOKEN}"))
+        .json(&json!({"reason": "compromised"}))
+        .send()
+        .await
+        .expect("Failed to revoke the static endpoint");
+    assert_eq!(revoked.status(), StatusCode::NO_CONTENT);
+    wait_for_submitted(&http, &fixture, GITHUB_ENDPOINT_ID).await;
+
+    let restarted = http
+        .post(format!("{api_url}/sources/{GITHUB_INSTANCE}/restart"))
+        .header("api-key", API_KEY)
+        .send()
+        .await
+        .expect("Failed to restart the source connector");
+    assert!(restarted.status().is_success());
+    wait_for_source_status(&http, &api_url, ConnectorStatus::Running).await;
+    wait_for_gateway(&http, &fixture).await;
+
+    let after = http
+        .post(fixture.webhook_url(GITHUB_ENDPOINT_ID))
+        .header(
+            GITHUB_HMAC_HEADER,
+            fixture.github_signature(body.as_bytes()),
+        )
+        .body(body)
+        .send()
+        .await
+        .expect("Failed to POST after the restart");
+    assert_eq!(
+        after.status(),
+        StatusCode::NOT_FOUND,
+        "the tombstone must outlive the restart even though http_github.toml still declares this endpoint"
+    );
+}
+
+/// Keep-alive is off on purpose. The gateway shuts down gracefully, so an idle
+/// pooled socket holds the listener open until its shutdown timeout expires,
+/// stalling harness teardown for seconds per test.
+fn webhook_client() -> Client {
+    Client::builder()
+        .pool_max_idle_per_host(0)
+        .build()
+        .expect("Failed to build the webhook client")
+}
+
+/// The listener binds during the connector's `open()`, which happens after the
+/// runtime's own HTTP API is already answering.
+async fn wait_for_gateway(http: &Client, fixture: &HttpSourceFixture) {

Review Comment:
   this returns as soon as the first instance joins, so any test needing both races the second one. `two_instances_share_one_listener` posts to `PARTNER_ENDPOINT_ID` and gets a 404 if `http_partner` has not joined yet, and `management_registered_endpoint_accepts_until_revoked` registers against `http_github` and gets "unknown instance" if that one is later. poll `/admin/health` until both names appear.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {

Review Comment:
   `buffer_capacity`, `max_batch_size` and `max_body_size_bytes` all get a floor and no ceiling. crossfire asserts `cap < (1 << 31)` while building the ring, and that panic unwinds out of `iggy_source_open`, which is `extern "C"` - the runtime wraps it in no `catch_unwind`, so a typo'd capacity aborts the whole connectors process along with every other plugin in it. below 2^31 you get an OOM instead, since crossfire allocates and stamps every slot eagerly.
   
   the check cannot live in `validate()`: the SDK builds the source before it calls `open()`, so the ring already exists by the time this runs. it has to be in `new()`.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1659 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::ArcSwap;
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+pub async fn leave(instance: &Arc<SharedState>) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let remaining: Vec<Arc<SharedState>> = server
+        .state
+        .instances()
+        .into_iter()
+        .filter(|joined| joined.id != instance.id)
+        .collect();
+    let remaining_count = remaining.len();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    server
+        .state
+        .metrics
+        .forget_instance(&instance.instance_name);

Review Comment:
   `SourceContainer::open` keeps the source even when `open()` returned an error, and `stop_connector` closes unconditionally, so a later stop or restart runs `leave()` for an instance that never joined this listener. when the failure was the duplicate-name rejection, this line wipes the gauges of the sibling that legitimately owns that name. it also rebuilds the route table for nothing and logs a deregistration that never happened. bail out early unless this instance is actually in `instances`.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,303 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result: the runtime NACKs a batch it could not send, or whose state it could not persist, and this connector holds that batch and replays it on the next `poll()` rather than dropping it. Nothing is ever abandoned, because answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 the handlers return once the bridge fills.

Review Comment:
   this says the runtime NACKs a batch whose state it could not persist, and that nothing is ever abandoned. neither holds for a state-only batch today - see `on_nack` in lib.rs.
   
   line 230 has the same problem: the tombstone does not survive an unreadable state file, which is exactly the fail-open restore. and line 232 points operators at `submitted`, the one flag that already flipped true before the state left the plugin. these three want fixing in this PR even if the code fixes land later.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1659 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::ArcSwap;
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+pub async fn leave(instance: &Arc<SharedState>) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let remaining: Vec<Arc<SharedState>> = server
+        .state
+        .instances()
+        .into_iter()
+        .filter(|joined| joined.id != instance.id)
+        .collect();
+    let remaining_count = remaining.len();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    server
+        .state
+        .metrics
+        .forget_instance(&instance.instance_name);
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    routes: ArcSwap<RouteTable>,
+    instances: ArcSwap<Vec<Arc<SharedState>>>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            routes: ArcSwap::from_pointee(RouteTable::default()),
+            instances: ArcSwap::from_pointee(Vec::new()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        (**self.instances.load()).clone()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.instances
+            .load()
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.routes.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.secret_path_count(),
+            dropped.named_path_count(),
+            self.instances.load().len()
+        );
+        self.routes.store(Arc::new(RouteTable::default()));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let table = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.instances.store(Arc::new(instances));
+        self.routes.store(Arc::new(table));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone()),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = state.routes.load();
+    let Some(instance) = routes.lookup_named_path(topic_path) else {
+        return (
+            UNROUTED.to_owned(),
+            error_response(StatusCode::NOT_FOUND, "not found"),
+        );
+    };
+    let name = instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(instance, request_headers, remote_addr, body, &state.metrics);
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = state.routes.load();
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Expired(entry) => {

Review Comment:
   the revoked arm above returns 404 so a leaked url cannot be used to confirm it was ever live, but expired returns 410 unconditionally and before any auth. anyone holding a leaked or guessed id can tell "existed" from "never existed" with no credential. make it 404 too.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {
+            return Err(Error::InvalidConfigValue(
+                "buffer_capacity must be at least 1".to_string(),
+            ));
+        }
+        if self.max_batch_size == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_batch_size must be at least 1".to_string(),
+            ));
+        }
+        if self.max_body_size_bytes == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_body_size_bytes must be at least 1".to_string(),
+            ));
+        }
+        if let Some(instance_name) = &self.instance_name
+            && HeaderKey::try_from(instance_name.as_str()).is_err()
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+            )));
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {

Review Comment:
   `hmac_header` never gets this check, though it is the same failure class in the same crate. an invalid header name makes `HeaderMap::get` return `None`, so every signed request 401s forever with nothing in the log naming the cause. `POST /admin/endpoints` has the same gap.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {
+            return Err(Error::InvalidConfigValue(
+                "buffer_capacity must be at least 1".to_string(),
+            ));
+        }
+        if self.max_batch_size == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_batch_size must be at least 1".to_string(),
+            ));
+        }
+        if self.max_body_size_bytes == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_body_size_bytes must be at least 1".to_string(),
+            ));
+        }
+        if let Some(instance_name) = &self.instance_name
+            && HeaderKey::try_from(instance_name.as_str()).is_err()
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+            )));
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        for endpoint in &self.endpoints {
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        let registry = EndpointRegistry::restore(&config.endpoints, state, id);
+        let (sender, receiver) = crossfire::mpsc::bounded_async(config.buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: Mutex::new(None),
+        }
+    }
+
+    pub fn shared(&self) -> &Arc<SharedState> {
+        &self.shared
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    async fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.staged.lock().await;
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    async fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.staged.lock().await = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    async fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.staged.lock().await;
+        let Some(batch) = staged.as_mut() else {

Review Comment:
   a state-only poll stages nothing, since `stage()` skips empty batches, so this early return drops the mutation for good. `take_dirty_state` already cleared `registry_dirty` and called `mark_submitted()` before the state left, and the runtime NACKs on a state save failure too, not only on a send failure. so a revoke is silently lost, `GET /admin/endpoints` still reports `submitted: true`, and the endpoint comes back on the next restart.
   
   fix: on a nack with no staged batch, set `registry_dirty` back to true and `state_flush.notify_one()`. moving `mark_submitted` into the ack arm instead does not work - a revoke landing between poll and ack would be marked submitted without ever having been handed out.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1659 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::ArcSwap;
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+pub async fn leave(instance: &Arc<SharedState>) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let remaining: Vec<Arc<SharedState>> = server
+        .state
+        .instances()
+        .into_iter()
+        .filter(|joined| joined.id != instance.id)
+        .collect();
+    let remaining_count = remaining.len();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    server
+        .state
+        .metrics
+        .forget_instance(&instance.instance_name);
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    routes: ArcSwap<RouteTable>,
+    instances: ArcSwap<Vec<Arc<SharedState>>>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            routes: ArcSwap::from_pointee(RouteTable::default()),
+            instances: ArcSwap::from_pointee(Vec::new()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        (**self.instances.load()).clone()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.instances
+            .load()
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        let dropped = self.routes.load();
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.secret_path_count(),
+            dropped.named_path_count(),
+            self.instances.load().len()
+        );
+        self.routes.store(Arc::new(RouteTable::default()));
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let table = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.instances.store(Arc::new(instances));
+        self.routes.store(Arc::new(table));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind(&config.listen_addr).await?;
+        let admin = bind(&config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone()),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+async fn bind(address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener to {address}. {error}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+fn public_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        .with_state(state)
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        named_path_outcome(&state, &topic_path, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request_headers: HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> Response {
+    let started = Instant::now();
+    let (instance_name, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, &request_headers, body);
+    state.metrics.record_request(
+        &instance_name,
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// Returns the instance the request resolved to alongside the response, so
+/// the caller can label the metrics. Requests that never resolved are still
+/// counted, under [`UNROUTED`].
+fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = state.routes.load();
+    let Some(instance) = routes.lookup_named_path(topic_path) else {
+        return (
+            UNROUTED.to_owned(),
+            error_response(StatusCode::NOT_FOUND, "not found"),
+        );
+    };
+    let name = instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(request_headers), expected)
+    {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(instance, request_headers, remote_addr, body, &state.metrics);
+    (name, response)
+}
+
+fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request_headers: &HeaderMap,
+    body: Result<Bytes, BytesRejection>,
+) -> (String, Response) {
+    let routes = state.routes.load();
+    let entry = match routes.lookup_secret_path(endpoint_id, unix_now_seconds()) {
+        RouteLookup::Active(entry) => entry,
+        // Revoked endpoints answer as if they never existed, so a leaked URL
+        // cannot be used to confirm it was once live. The metric still names
+        // the owning instance: only a genuinely unknown path is `unrouted`.
+        RouteLookup::Revoked(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+        RouteLookup::Expired(entry) => {
+            return (
+                entry.instance.instance_name.clone(),
+                error_response(StatusCode::GONE, "gone"),
+            );
+        }
+        RouteLookup::Unknown => {
+            return (
+                UNROUTED.to_owned(),
+                error_response(StatusCode::NOT_FOUND, "not found"),
+            );
+        }
+    };
+    let name = entry.instance.instance_name.clone();
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => return (name, rejected_body_response(rejection)),
+    };
+    if !authorize(&entry.endpoint, request_headers, &body) {
+        return (
+            name,
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+    let response = enqueue(
+        &entry.instance,
+        request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (name, response)
+}
+
+/// Prometheus text format. Unguarded like `/admin/health`: the admin
+/// listener defaults to loopback and scrapers do not carry bearer tokens.
+async fn handle_admin_metrics(State(state): State<Arc<ServerState>>) -> String {
+    state.metrics.encode(&state.instances())
+}
+
+/// Readiness for a load balancer: unavailable until an instance is serving.
+async fn handle_health(State(state): State<Arc<ServerState>>) -> Response {
+    if state.instances.load().is_empty() {

Review Comment:
   a non-empty `instances` does not mean anything is polling. the SDK stops the poll task after five consecutive NACKs without calling `close()`, so the instance stays joined, this keeps answering 200 to the load balancer, and handlers accept until the bridge fills and then 429 forever. the predicate needs all three: instances, routes, and a recent poll.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3869266724


##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,314 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, enforced by the `Bytes` extractor. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On a known path the body is buffered before authentication, which HMAC-over-raw-body requires. Must match across instances sharing a listener. |

Review Comment:
   stale since the named-path auth fix. `named_path_outcome` checks the bearer before it reads the body now, so buffering-before-auth is only true on the secret path, where hmac needs it.
   
   same row: the cap is enforced by the `Bytes` extractor on `/e/{id}` only - the named path applies it by hand with `axum::body::to_bytes`.



##########
core/connectors/sources/http_source/src/metrics.rs:
##########
@@ -0,0 +1,448 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Gateway-side Prometheus metrics, served on the admin listener.
+//!
+//! The runtime's own stage histograms start at `poll()`, so they cannot see
+//! anything a webhook sender experiences. This connector is an HTTP server, so
+//! it measures its own handling: the clock starts once axum has run the
+//! extractors, which means the request body has already been read. Time spent
+//! receiving a slow or large upload therefore sits outside the histogram, and
+//! accept-to-200 would need a tower layer wrapping the extractors.
+//!
+//! Names carry an `http_source_` prefix to keep them clear of the runtime's
+//! `iggy_connector_` family. One registry per shared listener, with every
+//! series labelled by instance.
+
+use prometheus_client::encoding::text::encode;
+use prometheus_client::encoding::{EncodeLabelSet, EncodeLabelValue, LabelValueEncoder};
+use prometheus_client::metrics::counter::Counter;
+use prometheus_client::metrics::family::Family;
+use prometheus_client::metrics::gauge::Gauge;
+use prometheus_client::metrics::histogram::Histogram;
+use prometheus_client::registry::Registry;
+use std::fmt;
+use std::sync::Arc;
+use std::time::Duration;
+use tracing::error;
+
+use crate::SharedState;
+use crate::routes::EndpointOrigin;
+use crate::types::unix_now_seconds;
+
+/// Instance label for requests that never resolved to one, so a scan for
+/// live endpoint ids still shows up rather than going uncounted.
+pub const UNROUTED: &str = "unrouted";
+
+/// Sub-millisecond at the low end: accepting a webhook is a route lookup, a
+/// signature check, and a channel send, so the interesting range is tight.
+const REQUEST_BUCKETS_SECONDS: [f64; 12] = [
+    50e-6, 100e-6, 250e-6, 500e-6, 1e-3, 2.5e-3, 5e-3, 10e-3, 25e-3, 50e-3, 100e-3, 500e-3,
+];
+
+/// Which surface a request arrived on.
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum PathKind {
+    Named,
+    Secret,
+}
+
+/// Response class, coarse on purpose: a per-status-code label would let a
+/// caller inflate cardinality by probing.
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum StatusClass {
+    Success,
+    Redirect,
+    ClientError,
+    ServerError,
+}
+
+impl From<u16> for StatusClass {
+    fn from(status: u16) -> Self {
+        match status {
+            200..=299 => Self::Success,
+            300..=399 => Self::Redirect,
+            400..=499 => Self::ClientError,
+            _ => Self::ServerError,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct InstanceLabel {
+    pub instance: String,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct RequestLabels {
+    pub instance: String,
+    pub kind: PathKind,
+    pub status: StatusClass,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct DurationLabels {
+    pub instance: String,
+    pub status: StatusClass,
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
+pub struct EndpointLabels {
+    pub instance: String,
+    pub kind: EndpointOrigin,
+}
+
+#[derive(Debug)]
+pub struct Metrics {
+    registry: Registry,
+    requests: Family<RequestLabels, Counter>,
+    request_duration_seconds: Family<DurationLabels, Histogram, fn() -> Histogram>,
+    rejected_full: Family<InstanceLabel, Counter>,
+    dropped_on_close: Family<InstanceLabel, Counter>,
+    headers_clamped: Family<InstanceLabel, Counter>,
+    headers_dropped: Family<InstanceLabel, Counter>,
+    buffer_used: Family<InstanceLabel, Gauge>,
+    buffer_capacity: Family<InstanceLabel, Gauge>,
+    endpoints_active: Family<EndpointLabels, Gauge>,
+}
+
+impl Metrics {
+    pub fn new() -> Self {
+        let mut registry = Registry::default();
+        let requests = Family::<RequestLabels, Counter>::default();
+        let request_duration_seconds: Family<DurationLabels, Histogram, fn() -> Histogram> =
+            Family::new_with_constructor(request_histogram);
+        let rejected_full = Family::<InstanceLabel, Counter>::default();
+        let dropped_on_close = Family::<InstanceLabel, Counter>::default();
+        let headers_clamped = Family::<InstanceLabel, Counter>::default();
+        let headers_dropped = Family::<InstanceLabel, Counter>::default();
+        let buffer_used = Family::<InstanceLabel, Gauge>::default();
+        let buffer_capacity = Family::<InstanceLabel, Gauge>::default();
+        let endpoints_active = Family::<EndpointLabels, Gauge>::default();
+
+        registry.register(
+            "http_source_requests",
+            "Webhook requests by path kind and response class",
+            requests.clone(),
+        );
+        registry.register(
+            "http_source_request_duration_seconds",
+            "Time from request accepted to response, in seconds",
+            request_duration_seconds.clone(),
+        );
+        registry.register(
+            "http_source_rejected_full",
+            "Requests answered 429 because the instance bridge was full",

Review Comment:
   help text says 429, but `enqueue` also bumps this on the disconnected branch, which answers 503. that branch exists so the loss isn't filed as backpressure, then files it there anyway. either give it its own counter or reword. readme line 280 lists it under 429 too.



##########
core/connectors/sources/http_source/src/routes.rs:
##########
@@ -0,0 +1,456 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Route table for a shared listener.
+//!
+//! Every instance joining a listener contributes its named topic path and its
+//! secret-path endpoints. The merged table is rebuilt and swapped whole on
+//! join, leave, and management mutations, so a request resolves its auth
+//! requirements and its destination bridge from one wait-free snapshot.
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::fmt::{self, Display, Formatter};
+use std::sync::Arc;
+
+use crate::types::EndpointId;
+use crate::{EndpointAuthType, SharedState, StaticEndpointConfig};
+
+/// Lifecycle state of a secret-path endpoint.
+///
+/// Revocation writes a tombstone rather than deleting the entry: the tombstone
+/// persists through a restart, so a stale TOML entry can never resurrect an
+/// endpoint an operator revoked.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointState {
+    Active,
+    Revoked { reason: String, revoked_at: u64 },
+}
+
+impl EndpointState {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked { .. } => "revoked",
+        }
+    }
+}
+
+/// Where an endpoint came from, which decides whether a TOML edit plus an
+/// instance restart or a management API call is the way to change it.
+#[derive(Debug, Clone, Copy, Default, Hash, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointOrigin {
+    #[default]
+    Static,
+    Dynamic,
+}
+
+impl EndpointOrigin {
+    /// Deliberately not `Display`: the metrics encoder wants a `&str` and
+    /// would allocate one per series on every scrape.
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Static => "static",
+            Self::Dynamic => "dynamic",
+        }
+    }
+}
+
+/// A secret-path endpoint served at `POST /e/{endpoint_id}`.
+///
+/// Persisted verbatim into the runtime state directory, HMAC and bearer
+/// secrets included, so endpoints created through the management API survive a
+/// restart. That file is as sensitive as the TOML it mirrors, which is why the
+/// README requires `chmod 700` on the state path.
+/// Fields added after the first release must be APPENDED and carry
+/// `#[serde(default)]`. `ConnectorState` uses rmp's compact codec, where a
+/// struct is a positional array, so a new field without a default makes every
+/// existing state file fail to decode, and `EndpointRegistry::restore` turns a
+/// decode failure into "tombstones lost, revoked endpoints served again".
+///
+/// `auth_type` and `state` deliberately have no default: for those two, a
+/// missing element must fail the decode rather than read as an active,
+/// unauthenticated endpoint.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Endpoint {
+    pub endpoint_id: EndpointId,
+    // No default: an absent auth_type must fail the decode, not silently
+    // read as `None` and drop the second factor.
+    pub auth_type: EndpointAuthType,
+    #[serde(default, serialize_with = "crate::state::serialize_secret_to_state")]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default)]
+    pub hmac_header: String,
+    #[serde(default)]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+    #[serde(default)]
+    pub origin: EndpointOrigin,
+    // No default: `EndpointState::default()` would be `Active`, so a record
+    // short by one element would resurrect a revoked endpoint - turning a
+    // loud decode failure into a silent, fail-open one.
+    pub state: EndpointState,
+    /// Whether this endpoint has been handed to the runtime for persistence.
+    /// Reset on every mutation, never itself persisted: a restored endpoint is
+    /// durable by definition. Not named `persisted`, because the plugin gets
+    /// no acknowledgement that the runtime's write actually landed.
+    #[serde(skip)]
+    pub submitted: bool,
+}
+
+impl Endpoint {
+    pub fn is_active(&self) -> bool {
+        matches!(self.state, EndpointState::Active)
+    }
+
+    /// Whether a request arriving now would be accepted.
+    pub fn is_serving(&self, now_seconds: u64) -> bool {
+        self.is_active() && !self.is_expired(now_seconds)
+    }
+
+    pub fn is_expired(&self, now_seconds: u64) -> bool {
+        self.expires_at
+            .is_some_and(|expires_at| now_seconds >= expires_at)
+    }
+
+    pub fn revoke(&mut self, reason: String, revoked_at: u64) {
+        self.state = EndpointState::Revoked { reason, revoked_at };
+        self.submitted = false;
+        // The handler 404s on a revoked entry before `authorize()` runs, so
+        // the secret is already dead weight. Keeping it would serialize a
+        // leaked credential into the state file, and nothing compacts
+        // tombstones, so revoking *because* it leaked would persist it
+        // indefinitely.
+        self.auth_secret = None;
+    }
+}
+
+impl From<&StaticEndpointConfig> for Endpoint {
+    fn from(config: &StaticEndpointConfig) -> Self {
+        Endpoint {
+            endpoint_id: config.endpoint_id.clone(),
+            auth_type: config.auth_type,
+            auth_secret: config.auth_secret.clone(),
+            hmac_header: config.hmac_header.clone(),
+            hmac_prefix: config.hmac_prefix.clone(),
+            expires_at: config.expires_at,
+            origin: EndpointOrigin::Static,
+            state: EndpointState::Active,
+            // Declared in TOML, so it needs no state file to come back.
+            submitted: true,
+        }
+    }
+}
+
+/// Immutable snapshot of every path one shared listener serves.
+#[derive(Debug, Default)]
+pub struct RouteTable {
+    secret_paths: HashMap<EndpointId, RouteEntry>,
+    named_paths: HashMap<String, Arc<SharedState>>,
+}
+
+/// A resolved secret path: the endpoint's own auth rules plus the instance
+/// whose bridge receives the body.
+#[derive(Debug)]
+pub struct RouteEntry {
+    pub instance: Arc<SharedState>,
+    pub endpoint: Endpoint,
+}
+
+/// Outcome of resolving a secret path. `Revoked` and `Unknown` both answer 404
+/// so the table never leaks which endpoints once existed; they stay distinct
+/// here so the handler can log and meter them apart.
+#[derive(Debug)]
+pub enum RouteLookup<'a> {
+    Active(&'a RouteEntry),
+    /// Carries its entry even though the response hides it, so the request can
+    /// still be metered against the instance that owns the endpoint.
+    Revoked(&'a RouteEntry),
+    Expired(&'a RouteEntry),
+    Unknown,
+}
+
+/// Two instances claiming the same path. Fails the join rather than letting
+/// whichever instance opened last silently steal another's traffic.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RouteConflict {
+    EndpointId {
+        endpoint_id: EndpointId,
+        held_by: u32,
+        claimed_by: u32,
+    },
+    TopicPath {
+        topic_path: String,
+        held_by: u32,
+        claimed_by: u32,
+    },
+}
+
+impl RouteTable {
+    /// Whether anything is routable. An instance with every endpoint revoked
+    /// or expired and no named path serves nothing, however joined it is.

Review Comment:
   `build()` inserts every endpoint, revoked and expired included, so `secret_paths` is non-empty for any instance that has ever had one. an instance with everything revoked and no named path still reads as routable here and `handle_health` answers 200. either filter on `is_serving` or drop the claim.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,314 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee. Consumers that need effectively-once processing should dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it, and real secrets
+# supplied through the runtime's env overrides rather than written here.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts** — set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, enforced by the `Bytes` extractor. Routing wins over it: an oversized POST to an unknown path answers 404, not 413. On a known path the body is buffered before authentication, which HMAC-over-raw-body requires. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, though see Backpressure: until #3795 lands that signals an arrival burst, not a slow Iggy. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie` — forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"service temporarily unavailable"}` plus `Retry-After: 1` |
+| 503 | `GET /health` with no instance serving | `{"status":"unavailable"}` |

Review Comment:
   503 also comes out of `enqueue` when the bridge has no receiver, not just from `/health`. worth its own row or folding into this one.



##########
core/connectors/sources/http_source/src/routes.rs:
##########
@@ -0,0 +1,456 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Route table for a shared listener.
+//!
+//! Every instance joining a listener contributes its named topic path and its
+//! secret-path endpoints. The merged table is rebuilt and swapped whole on
+//! join, leave, and management mutations, so a request resolves its auth
+//! requirements and its destination bridge from one wait-free snapshot.
+
+use secrecy::SecretString;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::fmt::{self, Display, Formatter};
+use std::sync::Arc;
+
+use crate::types::EndpointId;
+use crate::{EndpointAuthType, SharedState, StaticEndpointConfig};
+
+/// Lifecycle state of a secret-path endpoint.
+///
+/// Revocation writes a tombstone rather than deleting the entry: the tombstone
+/// persists through a restart, so a stale TOML entry can never resurrect an
+/// endpoint an operator revoked.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointState {
+    Active,
+    Revoked { reason: String, revoked_at: u64 },
+}
+
+impl EndpointState {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked { .. } => "revoked",
+        }
+    }
+}
+
+/// Where an endpoint came from, which decides whether a TOML edit plus an
+/// instance restart or a management API call is the way to change it.
+#[derive(Debug, Clone, Copy, Default, Hash, PartialEq, Eq, Serialize, Deserialize)]
+pub enum EndpointOrigin {
+    #[default]
+    Static,
+    Dynamic,
+}
+
+impl EndpointOrigin {
+    /// Deliberately not `Display`: the metrics encoder wants a `&str` and
+    /// would allocate one per series on every scrape.
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::Static => "static",
+            Self::Dynamic => "dynamic",
+        }
+    }
+}
+
+/// A secret-path endpoint served at `POST /e/{endpoint_id}`.
+///
+/// Persisted verbatim into the runtime state directory, HMAC and bearer
+/// secrets included, so endpoints created through the management API survive a
+/// restart. That file is as sensitive as the TOML it mirrors, which is why the
+/// README requires `chmod 700` on the state path.
+/// Fields added after the first release must be APPENDED and carry
+/// `#[serde(default)]`. `ConnectorState` uses rmp's compact codec, where a
+/// struct is a positional array, so a new field without a default makes every
+/// existing state file fail to decode, and `EndpointRegistry::restore` turns a
+/// decode failure into "tombstones lost, revoked endpoints served again".
+///
+/// `auth_type` and `state` deliberately have no default: for those two, a
+/// missing element must fail the decode rather than read as an active,
+/// unauthenticated endpoint.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Endpoint {
+    pub endpoint_id: EndpointId,
+    // No default: an absent auth_type must fail the decode, not silently

Review Comment:
   this holds for `state` but not for `auth_type`. rmp compact writes the struct as a positional array, so a record can only ever be short from the end - `auth_type` sits at index 1 of 8, so it can't be the missing one unless the array is down to a single element. `state` is last, so the guard there is the one doing the work.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,1941 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::rejection::BytesRejection;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            return Err(Error::InitError(format!(
+                "The {CONNECTOR_NAME} listener on {listen_addr} is shutting down; retry the open once its port is released"
+            )));
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish. `publish` is
+    // all-or-nothing, so on its failure branch the departed instance is still
+    // in `instances`, and counting the local vec would leave a listener bound
+    // for the life of the process: the next `leave` would see two instances,
+    // compute one remaining, and never reach the shutdown branch.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        SERVERS.lock().await.remove(listen_addr);
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    admin_listen_addr: String,
+    max_body_size_bytes: usize,
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]

Review Comment:
   `Published` got inserted between `ServerState`'s doc line and `ServerState` itself, so it now carries both that doc comment and the `#[derive(Debug)]` that belonged there - and `ServerState` has neither.
   
   move the doc line and `#[derive(Debug)]` back above `pub(crate) struct ServerState`, and make this `#[derive(Debug, Default)]`.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3867621898


##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,1305 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+pub mod auth;
+pub mod management;
+pub mod metrics;
+pub mod routes;
+pub mod server;
+pub mod state;
+pub mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::HeaderName;
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::auth::HmacAlgorithm;
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    pub id: u32,
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    staged: Mutex<Option<StagedBatch>>,
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: Mutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    pub state_flush: Notify,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry, one atomic load per request.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation and arms the next state flush.
+    pub async fn mutate_registry<R>(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> R) -> R {
+        let outcome = {
+            let _writer = self.registry_writer.lock().await;
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            let outcome = mutation(&mut next);
+            self.registry.store(Arc::new(next));
+            self.registry_dirty.store(true, Ordering::Release);
+            outcome
+        };
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        outcome
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, and an empty send always succeeds,
+    /// so attaching state to a batch that could fail would let the save be
+    /// skipped while this side had already cleared the flag and marked the
+    /// registry submitted - losing a revocation tombstone with no trace.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-arm rather than sleep on a flush
+            // that no further traffic would ever carry.
+            self.state_flush.notify_one();
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. Re-arm and re-notify, or the
+            // retry this promises would wait for unrelated traffic.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.state_flush.notify_one();
+            return None;
+        };
+        let mut persisted = EndpointRegistry::clone(&snapshot);
+        persisted.mark_submitted();
+        self.registry.store(Arc::new(persisted));
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it — and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+    #[serde(default)]
+    pub verbose_logging: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 410 Gone.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    pub fn hmac_algorithm(self) -> Option<HmacAlgorithm> {
+        match self {
+            Self::HmacSha256 => Some(HmacAlgorithm::HmacSha256),
+            Self::HmacSha1 => Some(HmacAlgorithm::HmacSha1),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 {
+            return Err(Error::InvalidConfigValue(
+                "buffer_capacity must be at least 1".to_string(),
+            ));
+        }
+        if self.max_batch_size == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_batch_size must be at least 1".to_string(),
+            ));
+        }
+        if self.max_body_size_bytes == 0 {
+            return Err(Error::InvalidConfigValue(
+                "max_body_size_bytes must be at least 1".to_string(),
+            ));
+        }
+        if let Some(instance_name) = &self.instance_name
+            && HeaderKey::try_from(instance_name.as_str()).is_err()
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+            )));
+        }
+        for header in &self.forward_headers {
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if matches!(
+                header.to_ascii_lowercase().as_str(),
+                "authorization" | "proxy-authorization" | "cookie"
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            if HeaderName::from_str(header).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        for endpoint in &self.endpoints {
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        let registry = EndpointRegistry::restore(&config.endpoints, state, id);
+        let (sender, receiver) = crossfire::mpsc::bounded_async(config.buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            registry_writer: Mutex::new(()),
+            state_flush: Notify::new(),
+        };
+        HttpSource {
+            id,
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: Mutex::new(None),
+        }
+    }
+
+    pub fn shared(&self) -> &Arc<SharedState> {
+        &self.shared
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    async fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.staged.lock().await;
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    async fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.staged.lock().await = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.

Review Comment:
   Fixed the README, but the `open()` guard cannot be written: the plugin never sees this value.
   
   `schema` is a field of the stream, not of the connector. It sits under `[[streams]]` alongside `stream`, `topic` and `batch_length`, and the runtime consumes it to build the encoder. What crosses the FFI boundary into the plugin is `[plugin_config]` and nothing else, so there is no `open()` in this crate that can read it, and adding a `schema` key to `[plugin_config]` would only let the two disagree.
   
   So the wedge you describe is real and this connector cannot defend against it. What I have done is correct the README, which claimed the batch is dropped: it NACKs, replays on every poll, and the SDK stops the poll task after five consecutive NACKs while the listener keeps answering 200. The paragraph now says that, and says why the check cannot live here.
   
   Where it could live is the runtime, which holds both halves: it knows the configured encoder and it sees `ProducedMessages::schema` on the first batch a source produces. Rejecting a source whose declared schema cannot encode what it emits would cover every source, not just this one, and would catch it on the first batch rather than after five NACKs. Happy to open that as a separate issue if you think it is worth having.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434049528

   All of the review is addressed. Two of your points I have to push back on, both with evidence, and one gap in my own earlier response that you were right about twice over.
   
   **The crossfire capacity claim is not correct, though the ask was.** You wrote that `buffer_capacity = 1` "selects crossfire's single-slot channel rather than the array one every real deployment uses". `crossfire::mpsc::bounded_async<T>(size)` is declared as returning `(MAsyncTx<Array<T>>, AsyncRx<Array<T>>)`, so the flavour is fixed by the signature and cannot vary with size; the one-slot flavour is `mpsc::One<T>`, a distinct type reached through a different constructor. The only documented special case is size 0, treated as 1.
   
   Both tests still moved to 2, because the reason holds even though the mechanism does not: at capacity 1 the ring is degenerate, so the test cannot distinguish a real capacity bound from an off-by-one. I had copied your wording into two comments before checking it, which is on me, and they now state the corrected reason.
   
   **The `leave()` guard does not have the consequence you described.** You said an unguarded teardown "wipes the metrics of the sibling that legitimately owns that name". `forget_instance` removes only gauges, and `Metrics::encode` re-derives every gauge from the live instances at the start of each scrape, so a still-joined sibling is never observably affected. I confirmed it by mutation: with the guard deleted the whole suite stays green, and the test I first wrote to catch it passed either way, so I deleted that test rather than keep one that cannot fail. The guard stays, because not rebuilding the route table for nothing and not logging a deregistration that never happened are worth the four lines, and the comment now says that instead.
   
   **You were right twice about `hmac_header` and I only fixed it once.** Your comment said `POST /admin/endpoints` has the same gap, and I added the check to the static config only. The dynamic path is the worse half: `HeaderMap::get` answers `None` for a name it cannot parse rather than failing, so a malformed one mints an endpoint that 401s every signed request forever, gives no clue why, and survives a restart because the field carries no validation on the restore path either. Fixed with a 400 and a test.
   
   Also fixed since the review: a state-only NACK no longer leaves a revocation unretried; `restore` fails `open()` instead of serving TOML without its tombstones; the management guard is a router layer so an unauthenticated request never reaches the body parser; expired endpoints answer 404; revocation clears the secret before it is persisted; `received_at_micros` no longer stamps the epoch on a broken clock; `mutate_registry` no longer arms a state write per no-op 404, which was an unbounded remote write on the #3940 backend from an authenticated caller; and `instance_name` can no longer claim the reserved `unrouted` metric label. Seven comment claims that were factually wrong are corrected, including three sites asserting "an empty send cannot fail", which #3940 made false by short-circuiting the send stage before the producer.
   
   Three things I have verified and deliberately not changed, since they are yours to call:
   
   - The public named path buffers the request body before the bearer check, exactly the ordering you flagged in `management.rs`. Fixing it properly means `ServerState` carrying the body limit and restructuring the handler to authorize before reading, so I did not want to reshape the request path without your say.
   - `submitted` still over-reports between a failed state save and the retry that succeeds. Clearing it means rewriting the registry from a sync path that cannot take the async writer lock, and risks discarding a revocation that landed in between. Documented rather than fixed.
   - The `setup_source_producer` cleanup asymmetry you flagged as not mine is real and worse than it looks: `manager/source.rs` returns early without `iggy_source_close`, and `details.info.id` is only assigned after that fallible step, so a later stop closes a stale id and the orphaned instance keeps answering 200 into a bridge nothing drains. Happy to send that runtime fix if you want it.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434306467

   /ready


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5626819921

   Round 6 from @numinnex: 12 findings, all 12 answered on their own threads. Detail is there; this is the short version.
   
   Five are fixed and pushed:
   
   - `docs(connectors): correct when an expired endpoint's secret leaves disk` — the expiry clear is in-memory and arms no flush, so the README's "dropped on the next restart" was false. Reworded, flag not armed, for the reason numinnex gave.
   - `fix(connectors): check the bridge before the body is read, not after` — the earlier fix landed inside `enqueue`, which is after the body read. Both handlers now check before `to_bytes`.
   - `docs(connectors): correct the batch copy count, and name the body term` — four concurrent copies, not three, and the paragraph now carries a term for in-flight request bodies.
   - `fix(connectors): frame the state file so a short read cannot fail open` — a shortened state blob decoded `Ok` with zero tombstones, which put revoked static endpoints back on the wire with their secrets. Framed with a version, a declared count and a consumed-length check.
   - The same commit covers the zero-length-file route into that same fail-open: a warn when an instance starts with static endpoints and no registry, and the README now says truncating the state file is the same act as deleting it.
   
   201 unit tests, and the two restart integration tests pass on the new state format.
   
   Seven are accepted and queued, in this order: `lib.rs:887`, then `lib.rs:987` with `lib.rs:954` as one change, then `server.rs:580`, `state.rs:284`, `lib.rs:529`, and `server.rs:278` last because it moves where routes get published.
   
   One thing worth surfacing beyond the finding. I swept the state decode rather than trusting the three repros: every single-byte mutation of a real blob plus every prefix, and nothing decodes with fewer endpoints than it was written with. But 480 of those mutations edit a byte inside an endpoint id, which yields a well-formed frame still carrying its tombstone under a different id, so the original id serves again. That is a file integrity property rather than a decode one and this framing was never going to catch it. Happy to file it separately if you think it is worth its own issue.
   
   Not requesting a re-review, the PR is already `S-waiting-on-review`.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984645383


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,

Review Comment:
   Correction to my reply above: I said the id retargeting wanted a different mechanism and offered it as a separate issue. That was wrong, and the mechanism was already in the file. Fixed in `fix(connectors): refuse a state file that misfiles an endpoint under a new id`.
   
   An endpoint id is written twice, as the map key and inside the record, and `try_insert` always keys an endpoint by its own id, so the two agreeing is an invariant of every writer rather than a coincidence. `restore` was resolving a disagreement by preferring the key, which silently repaired precisely the corruption worth refusing. The decode rejects it now. A single edit cannot change both copies, so a retargeted tombstone always leaves them disagreeing.
   
   Measured rather than argued: all 480 of the retargeting mutations are caught, and the sweep now asserts the tombstone survives rather than only that the endpoint count does. Removing the check turns that test and a direct one red.
   
   No new format field and no checksum, which I had assumed this would need. Worth being explicit that a checksum would not have been the better answer anyway: this is corruption detection, not authentication. Anyone who can write the file can write a consistent one, and the file is a cleartext credential store, so they can already read every secret in it. The redundant id field was doing real work all along and `restore` was throwing it away.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3985448663


##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)

Review Comment:
   Fixed in `fix(connectors): publish an instance's routes when it can drain them`. This was the largest of the twelve and it went the way you described.
   
   The gate could not separate the two cases because `poll_is_live` is false both for a task that has stopped and for one that has not started, and those want opposite answers. An instance now records that it has ever polled, and readiness counts only those. A task that stops still takes the listener down, which is the case the gate exists for.
   
   Ignoring it would be a lie if it were serving in the meantime, so routes follow the same rule rather than only the health answer changing. They are projected from instances that have polled, and an instance publishes its own on its first poll rather than in `join`. Before that its paths answer 404, which is the honest answer while nothing can drain them. I took the rejection of a boot grace period as given: it answers 200 with no reader on the bridge, which is the failure the gate exists to prevent.
   
   One thing I had to keep that is easy to lose in this move. `join` published before binding on purpose, so a config that cannot produce a valid table does not leave a port bound. `publish` now builds twice: once across every joined instance, which is the check and has to see all of them so a conflict is refused at join rather than lying dormant until the offender first polls, and once across the subset that has polled, which is what gets served. Neither is on a request path.
   
   The test asserts both halves, since either alone would be wrong. A joined instance that has not polled leaves `/health` at 200 for its siblings, and its own named path answers 404 until its poll task runs, at which point it answers 200. Reverting the readiness filter gives 503 where 200 is expected, which is your symptom exactly; reverting the route filter gives 200 where 404 is expected.
   
   Worth saying where the real evidence is. The unit test stands in for the first poll, so it cannot prove the production path fires. The integration suite does: all 13 `connectors::http` tests pass against a real server and a real runtime poll task, and those never touch the test helper. `webhook_post_produces_message_to_iggy` delivering means `serve_routes` is actually being called from the poll loop.
   
   Nearly every request test in the crate had been relying on routes existing without a poll task, so the fixtures now stand in for that first poll. That is a fair amount of churn in the diff and none of it is behaviour.
   
   209 unit tests.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5547025575

   @hubcio rebased onto master (`40be16846`) and force-pushed. Head is now `6cb676b74`. The only conflict was one line in `Cargo.toml`. 148 unit tests and all 6 `connectors::http::http_source` integration tests pass locally.
   
   Could you re-run `Common checks / Markdown lint` when you get a chance? `gh run rerun` wants admin rights on the repo, so I can't.
   
   It failed at step 3, `Setup Node.js`, with `read ECONNRESET`. `Install markdownlint-cli` and `Run markdownlint` are both marked `skipped`, so the linter never ran. The job took 6s.
   
   https://github.com/apache/iggy/actions/runs/33922864613/job/101184851398
   
   The second red X, `finalize_pr`, is downstream of that one. Its `needs` list includes `common`, and the `Check status` step only aggregates what the other jobs did.
   
   Everything else on the run is green: 95 passed, 1 skipped, including every BDD suite. Repo-wide markdown lint passes here using the script's own invocation:
   
   ```
   markdownlint '**/*.md' --ignore-path .gitignore --ignore "helm/charts/iggy/README.md"
   ```
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5156564046

   <!-- iggy-pr-triage-welcome -->
   Thanks for the PR. It is labeled `S-waiting-on-review` and queued for review.
   
   Slash commands (own line, regular comment) move it around the queue:
   
   - `/ready` - back to `S-waiting-on-review` after addressing feedback
   - `/author` - flip to `S-waiting-on-author` while you finish changes
   - `/request-review @user-or-team` - request a reviewer
   
   See [CONTRIBUTING.md](https://github.com/apache/iggy/blob/master/CONTRIBUTING.md#pr-triage-commands) for details.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5589705914

   Thanks. You reviewed `4124da7e9`; the head is now `b02f643a7`, and five of these are already fixed in commits you have not seen. 188 unit tests and all 6 integration tests green.
   
   | Your comment | Fixed by |
   | --- | --- |
   | `lib.rs:691` expired endpoint fails the whole instance | `f41725176` |
   | `server.rs:637` named path resolved before the body read | `abc09dcbf` |
   | `server.rs:523` no `.fallback` | `04a2d536f` |
   | `README:240` status table | `04a2d536f` |
   | `README:114` no max column | `04a2d536f` |
   
   **One deviation worth naming.** On the expiry critical you said to scope the check to the endpoint the way `restore` does. What I shipped instead makes the config path skip the clock rule entirely: `admit_endpoint` now takes an `Admission` of `Creating` or `Existing`, and `validate()` passes `Existing`. Same outcome for the operator, different shape. Expiry is the only rule that does not survive being re-applied at every start, so putting that in the signature seemed better than scoping one call site. Say the word if you prefer the narrower fix.
   
   The named-path fix is your prescription exactly: re-lookup after the body read plus `Arc::ptr_eq`, copied from the secret path. The `ptr_eq` half has its own test now, because without one both guards degraded to a bare match arm with the whole suite still green.
   
   Four are new and I will take them:
   
   - `lib.rs:1593` `queued()` hardcoding `id: 0`, so nothing proves a replay keeps its id.
   - `http_source.rs:458` waiting on `submitted`, which only means the registry left the plugin. That is a flaky test of mine and it should wait on the state file.
   - `connector-source/SKILL.md:110` against pitfall 8.
   - `connector-testing/SKILL.md:57` against the canonical test at :139.
   
   **You are right about the dedupe claim, and I checked it before agreeing.** `core/server/src/http/wire.rs:61-64` mints an id when the incoming one is zero and never reads it again, so nothing server-side dedupes on `ProducedMessage.id`. `SKILL.md:103` and pitfall 7 are both wrong. This connector's README already says consumer-side, so only the skill needs the change.
   
   **Merge order: agreed, and it is your call.** #4062 is worse here than for other sources because the listener registry is process-global, so the orphan keeps the topic path and every endpoint id and only a full connectors restart clears it. #4064 is open with that fix and CI green. The two PRs share no files, so either order merges cleanly; landing #4064 first just means this one needs no mitigation for it.
   
   Two things also went in since your last look, from a review pass on my own changes: registration is now validated before it is published rather than rolled back after, and `restore` asks the same admission rule the API does instead of its own subset, which was silently letting an endpoint with no usable secret come back active and refuse every request.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5593323017

   Round 5 is done, at `3a560e9ae`, along with the six items my own double review
   had left verified but not implemented. Rebased onto master first. Gate green:
   fmt, sort, taplo, clippy at both feature sets, rustdoc `-D warnings`, `--locked`,
   markdownlint, **193 unit tests** (was 188) over three clean runs, and 25
   connectors integration tests including all 6 for this connector.
   
   ### The five from round 5
   
   | commit | finding |
   | --- | --- |
   | `23229b8f1` | `queued()` hardcoded `id: 0`, so nothing proved a replay keeps its id |
   | `fa266f8dd` | the flaky test: `submitted` is not "on disk" |
   | `d26cde465` | the dedupe claim, the listener contradiction, and the naming rule |
   
   **You were right about the dedupe claim, and I checked it rather than take it.**
   `core/server/src/http/wire.rs` mints a fresh uuid when the incoming id is 0 and
   otherwise passes it through, and that is the server's only read of the field.
   The dedup path is the per-client `dedup_clients_max` watermark, which never looks
   at it. Corrected in both places in the skill: the IDs section and pitfall 7,
   which promised idempotency. The connector README was already right.
   
   The naming rule turned out to rule out its own canonical example.
   `state_should_be_serializable_and_deserializable` has no `given_`, and that is
   its name in `random_source`, `postgres_source` and here. The rule now says a test
   whose subject is a type drops the prefix, rather than renaming three plugins to
   fit a doc.
   
   The flaky test is worth a word: waiting for the state file to merely *change* is
   not enough either, since a flush already in flight satisfies that. Each test now
   waits on a string only its own mutation writes.
   
   ### Two behaviour changes
   
   **`9c6818f60`, the named path answers 503 when it changes hands mid-request.**
   Your point about a transient 404 stands: that caller had already passed bearer
   auth, the path exists, and only which instance serves it changed, so a
   conventional client stops retrying. `management.rs` already answers 503 for the
   same condition. The secret path keeps 404 for both cases, because its caller is
   unauthenticated and separating "wrong id" from "busy" would confirm which ids
   exist.
   
   `3a560e9ae` corrects the body I first gave it. That arm answers for two
   conditions and "instance is closing" was true of only one: the second lookup
   returns nothing when the path was withdrawn, and a different instance when one on
   the same listener has taken the path over. It now says `route unavailable`, which
   holds for both, and it deliberately does not distinguish them, since the caller
   retries either way and the difference is listener topology.
   
   This nearly cost the identity guard its test. `enqueue` on a stranger already
   answers 503 for a disconnected bridge, and the swap test asserted 404 exactly to
   tell those apart. The rival's bridge is now kept live, so removing the
   `Arc::ptr_eq` yields `HTTP/1.1 200 OK` and the test fails on it. Stronger than
   before: it proves delivery happened rather than that a status differed.
   
   **`224cd8b42`, an expired endpoint no longer keeps its secret on disk.**
   `revoke()` clears `auth_secret` for a stated reason, and an expired endpoint is
   refused the same way and just as early, yet kept its secret. `restore` now drops
   it and says how many, which was also the only restore-time fault with no startup
   signal.
   
   What settled it was not the analogy to `revoke()` but the connector's own answer
   elsewhere: `rotate_secret` already refuses an expired endpoint with "endpoint has
   expired; register a replacement". Expiry is therefore terminal here by design,
   not a pause, so keeping the credential preserves something nothing can use
   again. The endpoint keeps its slot: reclaiming it would make endpoints vanish on
   a clock condition rather than an operator action. Restore only, and the README
   says so.
   
   ### Four more from the double review
   
   `056f2307c` `/admin/health` loaded `published()` twice, so the instance array and
   the status could describe different publishes, which is the disagreement that
   value exists to prevent. One snapshot, one clock read, and one
   `Published::is_ready(now)` shared with `/health`.
   
   `ff18b9f3c` the three ceiling messages carried literal numbers. The existing
   ceiling tests cannot catch that drift because they build their inputs *from* the
   consts: raising `MAX_HMAC_HEADER_LEN` to 512 left both of them green and only the
   new test failed.
   
   `e5130a6a3` the re-resolve narrowed the uncounted-loss window but could not close
   it, since `enqueue` still builds the header map and copies the body after the
   gate. `leave()` now flags before it counts and `enqueue` checks after `try_send`.
   
   **One I did not do, and it is the same shape as the helper your review already
   talked me out of.** Extracting the second-snapshot-plus-`ptr_eq` step: both
   re-resolves hand back a reference into a `Guard` created inside the function, so
   a helper cannot own the guard and return it. Returning owned values means cloning
   a `RouteEntry` per request, and that type is not `Clone` precisely because it
   holds the `hmac_key` derived once per table rather than per request. After the
   503 change the two refusals differ deliberately as well, so a shared step would
   take the refusal as a parameter and be left sharing about two lines.
   
   ### #4064, and what it settles for this PR
   
   It is finished and pushed. All 18 of your inline findings are in, including both
   halves of the incomplete guard: the cancellation that left the `SOURCE_SENDERS`
   entry and both tasks behind, and the `block_on` teardown in drop glue.
   
   More useful here: **it closes the orphan case for this plugin completely, so
   nothing local is needed on this side.** `open()` joins the listener as its last
   fallible step, with only a log line after it, and every `join` failure path
   returns before the instance reaches the published table. So a failed `open()`
   never leaves a joined listener, and a successful one is covered by the guard for
   the whole window. The one remaining leak, `iggy_source_open` inserting into
   `INSTANCES` even when `open()` failed, therefore holds an inert object here: no
   listener, no route entry, no `instance_name` claim. That is your own out-of-diff
   finding and it still deserves its own issue, but it is not a live fault for this
   connector.
   
   I also filed #4097 for the multi-stream producer bug from that review:
   `setup_source_producer` `init()`s a producer per `[[streams]]` entry and keeps
   only the last, so two configured streams silently produce to one.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "numinnex (via GitHub)" <gi...@apache.org>.
numinnex commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3948469965


##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1288 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference,
+//! though the underlying flush covers the whole registry at once.
+
+use axum::extract::rejection::JsonRejection;
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{is_usable_secret, validate_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, bearer_header, error_response, refresh_routes};
+use crate::state::{InsertOutcome, MAX_ENDPOINTS};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+/// A revoke reason rides the tombstone, and tombstones are never evicted,
+/// so an uncapped one is an authenticated caller writing to the state file
+/// without limit.
+const MAX_REVOKE_REASON_LEN: usize = 256;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable_secret(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    // `authorize` never reads a secret for an unauthenticated endpoint, so
+    // accepting one only persists a credential nothing will ever check.
+    if request.auth_type == EndpointAuthType::None && request.auth_secret.is_some() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "auth_type 'none' takes no auth_secret",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+    };
+
+    let mut outcome = InsertOutcome::Collision;
+    instance.mutate_registry(|registry| {
+        outcome = registry.try_insert(endpoint);
+        outcome == InsertOutcome::Inserted
+    });
+    match outcome {
+        InsertOutcome::Inserted => {}
+        InsertOutcome::Collision => {
+            // 128 bits of entropy makes this unreachable in practice; refusing
+            // to overwrite is what keeps it from silently retargeting live
+            // traffic.
+            warn!(
+                "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+                instance_id = instance.id
+            );
+            return error_response(StatusCode::CONFLICT, "endpoint id collision");
+        }
+        InsertOutcome::Full => {
+            warn!(
+                "Registry for {CONNECTOR_NAME} connector ID: {instance_id} holds {MAX_ENDPOINTS} endpoints with no reclaimable tombstones, refusing the registration",
+                instance_id = instance.id
+            );
+            return error_response(
+                StatusCode::INSUFFICIENT_STORAGE,
+                "endpoint registry is full",
+            );
+        }
+    }
+    warn_if_poll_stopped(&instance, "Registered", endpoint_id.as_str());
+    if let Some(failure) = republish(&state).await {

Review Comment:
   `mutate_registry` (:161) publishes the endpoint, arms the dirty bit and posts the flush permit before this await, so the live poll task can snapshot that registry and the runtime can persist it while the handler is parked here. The rollback below cannot undo a flush that already happened, and the 503 branch at :202-207 declines to roll back at all because "that registry is already unreachable" - true of the future, false of the window that just closed. Either way the caller is told 500 or 503 while the endpoint is durable and serving after a restart, at a URL the response never returned.
   
   The tombstone half is the same ordering: `try_insert` may have reclaimed tombstones inside the clone that was already published (`state.rs:216-226`), and `registry.remove` restores only the new id, so a refused registration durably drops audit records. `pending_changes` is also incremented twice for a net-zero registration.
   
   Fix: two-phase - build the candidate registry, validate it against `RouteTable::build`, then publish and arm together. That retires the rollback entirely. Worth naming the two alternatives that look right and are not: arming the dirty bit after the verdict reverts `256ae51e0` into the fail-open direction, and holding `registry_writer` across this await puts a `std::sync::Mutex` across `SERVERS.lock().await` and makes `take_dirty_state`'s `try_lock` fail every poll, silently skipping flushes.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2002 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None
+                && !endpoint
+                    .auth_secret
+                    .as_ref()
+                    .is_some_and(|secret| !secret.expose_secret().is_empty())
+            {
+                // An empty key is perfectly valid for HMAC, so accepting one
+                // would leave `auth_type` advertising a second factor that
+                // anyone holding the URL can compute.
+                // Prefix only: this becomes `last_error`, which the runtime
+                // logs and serves over its control API, and the operator will
+                // fix the secret while keeping the id.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares auth_type {:?} but no non-empty auth_secret",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.auth_type
+                )));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl HttpSource {
+    pub fn new(id: u32, config: HttpSourceConfig, state: Option<ConnectorState>) -> Self {
+        // Clamped rather than rejected: `new` cannot fail, and an unchecked
+        // value reaches crossfire before `open` runs. `validate` still rejects
+        // it, so the operator learns through `last_error` instead of an abort.
+        let buffer_capacity = config.buffer_capacity.clamp(1, BUFFER_CAPACITY_LIMIT);
+        if buffer_capacity != config.buffer_capacity {
+            warn!(
+                "Clamped buffer_capacity {} to {buffer_capacity} for {CONNECTOR_NAME} connector ID: {id}",
+                config.buffer_capacity
+            );
+        }
+        // An unreadable registry cannot be served, but `new` has many callers and
+        // the SDK builds the source before it calls `open`, so the failure is
+        // carried to `open` rather than widening this signature. The empty
+        // registry it starts from serves nothing if that ever changed.
+        let (registry, restore_error) =
+            match EndpointRegistry::restore(&config.endpoints, state, id) {
+                Ok(registry) => (registry, None),
+                Err(error) => (EndpointRegistry::default(), Some(error.to_string())),
+            };
+        let (sender, receiver) = crossfire::mpsc::bounded_async(buffer_capacity);
+        let instance_name = config
+            .instance_name
+            .clone()
+            .unwrap_or_else(|| id.to_string());
+        // Entries that fail to resolve are rejected by `validate()` in
+        // `open()`, so the instance never serves traffic with a silent gap.
+        let forward_headers = config
+            .forward_headers
+            .iter()
+            .filter_map(|header| {
+                let name = HeaderName::from_str(header).ok()?;
+                let key = HeaderKey::try_from(header.as_str()).ok()?;
+                Some((name, key))
+            })
+            .collect();
+        let shared = SharedState {
+            id,
+            config,
+            sender,
+            instance_name,
+            forward_headers,
+            registry: ArcSwap::from_pointee(registry),
+            registry_dirty: AtomicBool::new(false),
+            pending_changes: AtomicUsize::new(0),
+            handed_changes: AtomicUsize::new(0),
+            poll_active: AtomicBool::new(false),
+            last_poll_at: AtomicU64::new(0),
+            registry_writer: StdMutex::new(()),
+            state_flush: Arc::new(Notify::new()),
+            state_flush_nacks: AtomicU32::new(0),
+        };
+        HttpSource {
+            shared: Arc::new(shared),
+            receiver: Mutex::new(receiver),
+            staged: StdMutex::new(None),
+            last_poll_was_state_only: AtomicBool::new(false),
+            restore_error,
+        }
+    }
+
+    /// A poisoned `staged` means a panic while a batch was held. The batch is
+    /// still intact, and refusing to look at it would lose it for certain.
+    fn lock_staged(&self) -> std::sync::MutexGuard<'_, Option<StagedBatch>> {
+        self.staged.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Re-emits the unacknowledged batch, if one is waiting.
+    fn staged_batch(&self) -> Option<ProducedMessages> {
+        let staged = self.lock_staged();
+        let staged = staged.as_ref()?;
+        debug!(
+            "Replaying {} unacknowledged messages after {} NACK(s) for {CONNECTOR_NAME} connector ID: {}",
+            staged.messages.len(),
+            staged.nacks,
+            self.shared.id
+        );
+        Some(ProducedMessages {
+            schema: Schema::Raw,
+            messages: staged.messages.iter().cloned().map(Into::into).collect(),
+            // State rides an empty batch only, and a replay is never empty.
+            state: None,
+        })
+    }
+
+    /// Holds `queued` until the runtime acknowledges it and converts it into
+    /// the batch to produce. The clone buys the ability to replay.
+    fn stage(&self, queued: Vec<QueuedMessage>) -> Vec<ProducedMessage> {
+        let messages: Vec<ProducedMessage> = queued.iter().cloned().map(Into::into).collect();
+        if !queued.is_empty() {
+            *self.lock_staged() = Some(StagedBatch {
+                messages: queued,
+                nacks: 0,
+            });
+        }
+        messages
+    }
+
+    /// Keeps a batch the runtime could not deliver so the next `poll()` replays
+    /// it. A batch is never abandoned here.
+    ///
+    /// Answering 200 told the sender this gateway owns the event, so the only
+    /// honest way to shed load is the 429 the handlers return once the bridge
+    /// fills, which senders retry. Dropping a staged batch instead would trade
+    /// that bounded, visible backpressure for silent loss growing with the
+    /// length of the outage, and no downstream can detect it.
+    ///
+    /// A batch that can never be delivered would replay forever, but this
+    /// connector rejects malformed work at the door rather than mid-stream:
+    /// oversized bodies get 413 before a handler runs, headers are clamped on
+    /// accept, and `Schema::Raw` cannot fail to decode.
+    fn on_nack(&self) -> Result<(), Error> {
+        let mut staged = self.lock_staged();
+        let Some(batch) = staged.as_mut() else {
+            drop(staged);
+            // Nothing staged means the batch carried no messages, which is
+            // usually a state flush the runtime could not persist or would not
+            // attempt. It can also be an empty batch that carried no state at
+            // all, when the writer gate was contended or nothing was dirty,
+            // and re-arming then costs one redundant flush rather than a lost
+            // one. `take_dirty_state` already cleared the flag, so re-arming
+            // here is the only thing that stops a revocation being lost while
+            // the API reports it durable. This is load-bearing, not defensive.
+            self.shared.rearm_state_flush();

Review Comment:
   The re-arm is unconditional, so a NACK of a batch that carried no state sets `registry_dirty` with `pending_changes == 0`. Reachable after any mutation: `mutate_registry` notifies once per mutation while one flush clears the flag for all of them, so the surplus permit fires the flush arm, `take_dirty_state` returns `None` (:407), an empty `state: None` batch goes out, and the SDK's shutdown arm NACKs any in-flight batch on every graceful stop.
   
   `close()` (:933-938) then logs `0 change(s) not submitted, so a change made since the last poll will not survive the restart` - a zero-count data-loss alarm on the one signal README:254 tells operators to trust, which is the false-report class `256ae51e0` was written to remove. It also spends `state_flush_nacks` on NACKs that had nothing to do with the state store.
   
   Fix: gate the re-arm on whether the batch just produced actually carried state, and write that marker on every exit of `poll()`, the staged-replay early return at :830-832 included.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2202 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+/// A request that resolved to no instance is still metered, under [`UNROUTED`],
+/// which is where a scan for live endpoint ids shows up.
+fn instance_label(instance: Option<&Arc<SharedState>>) -> &str {
+    instance.map_or(UNROUTED, |instance| instance.instance_name.as_str())
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) = named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// The instance the request resolved to, for the caller to label metrics with.
+/// Returning the `Arc` the lookup already produced rather than a copy of its
+/// name keeps the label allocation-free on the request path; `None` is a
+/// request that resolved to no instance, counted under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands them over owned, so nothing is cloned to survive the
+    // body being taken.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+        };
+        Arc::clone(instance)
+    };
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            Some(instance),
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (Some(instance), oversized_body_response(&error)),
+    };
+    let response = enqueue(
+        &instance,
+        &request_headers,
+        remote_addr,
+        body,
+        &state.metrics,
+    );
+    (Some(instance), response)
+}
+
+async fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands the headers over owned; taking them as an extractor
+    // cloned the whole map on every request.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let routes = &state.published().routes;

Review Comment:
   `&state.published().routes` is lifetime-extended to fn scope, so the `RouteEntry` resolved here and the clock read at :658 are still what `authorize` (:684) and `enqueue` (:695) use after `to_bytes().await` at :680. A concurrent revoke or rotate publishes the tombstone and answers 202 while every request whose lookup already ran is accepted 200 on the dead key. Body pacing is the client's, with no read timeout and no connection cap above it, so N pre-opened trickling connections buy N post-revocation accepts. `management.rs:351` and README:250 promise the opposite.
   
   Fix: scope this guard to a block, clone the `Arc<SharedState>` out for the metric label, drop the guard, await the body, then re-load `published()` and re-run `lookup_secret_path(endpoint_id, unix_now_seconds())`, requiring `Active` and `Arc::ptr_eq` on the instance. Dropping the guard is part of the fix, not style: re-looking up while still holding the first one closes the TOCTOU but keeps the whole `Published` pinned across a client-paced await. `named_path_outcome` (:613-619) is the shape.
   
   Note this window is a regression from `d4efca998` - the `Bytes` extractor it replaced read the body before the lookup, so it did not exist before.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2202 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances

Review Comment:
   This check is where #4062 stops being a leaked object and becomes terminal. `manager/source.rs:240-241` returns from `setup_source_producer` after `init_source` succeeded, without `iggy_source_close`, and `details.info.id` is not assigned until :261 - so the instance stays in `SERVERS` holding both ports and its routes for the life of the process. Every retried start then fails here; with `instance_name` unset it fails one line later instead, on `RouteConflict` from the orphan's own `topic_path` and static ids. Recovery is restarting the whole connectors process, taking every other plugin with it, and the trigger is the ordinary broker-unreachable-at-start case.
   
   For every other source that orphan is an unreachable in-memory object and the next start succeeds. What makes it unrecoverable here is the process-global listener registry, which is this PR's. Suggest treating #4062 as a merge dependency rather than a follow-up.
   
   If you want a local defense that does not wait on it: plugin ids are monotonic, so a joined instance with a strictly lower id that collides on name or path is provably an orphan and can be evicted on `open()`. It must not key on `poll_is_live`, which is false for any freshly opened sibling, and re-keying `SERVERS` by plugin id changes only which error you get, since the orphan still holds the routes.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,340 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `listen_addr` | string | required | Public listener. Every instance sharing it must configure the identical value. |
+| `admin_listen_addr` | string | `127.0.0.1:9091` | Management API, admin health, and metrics. Never route this through a public load balancer. |
+| `instance_name` | string | runtime id | Identifies the instance in message headers and on the admin listener. The default is the plugin's numeric runtime id, assigned in load order and **not stable across restarts**, so set it explicitly in production. |
+| `topic_path` | string | none | Exposes `POST /topics/{topic_path}`. Unset leaves only secret-path endpoints. |
+| `auth_bearer_token` | string | none | Guards the named topic path. Unset leaves it unauthenticated, for deployments behind an authenticating gateway. |
+| `management_token` | string | none | Enables `/admin/endpoints`. Unset means the management API does not exist. |
+| `max_body_size_bytes` | usize | `1048576` | Request body limit, applied by the handlers rather than an extractor. Routing wins over it: an oversized POST to an unknown or revoked path answers 404 without the body being read. Must match across instances sharing a listener. |
+| `buffer_capacity` | usize | `10000` | Messages the instance bridge holds. A full bridge answers 429, which since #3855 signals either an arrival burst or a slow Iggy, since the poll loop stalls waiting for the previous batch to be acknowledged. |
+| `max_batch_size` | usize | `500` | Maximum messages a single `poll()` returns. |
+| `include_http_metadata` | bool | `true` | Adds instance, peer address, and receive time as message headers. |
+| `forward_headers` | array | `[]` | Request headers copied onto the message. Invalid names fail `open()`, as do `Authorization`, `Proxy-Authorization`, and `Cookie`, because forwarding a reusable credential would copy it onto every message and persist it in the log. |
+| `endpoints` | array | `[]` | Static secret-path endpoints. |
+
+### Endpoint options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `endpoint_id` | string | required | Exactly 32 lowercase hex characters. Generate with `openssl rand -hex 16`. |
+| `auth_type` | string | `none` | `none`, `bearer`, `hmac-sha256`, or `hmac-sha1`. |
+| `auth_secret` | string | none | Required unless `auth_type` is `none`. |
+| `hmac_header` | string | `X-Hub-Signature-256` | Header carrying the signature. |
+| `hmac_prefix` | string | `sha256=` | Prefix stripped before hex-decoding. Use `""` for a bare hex signature. |
+| `expires_at` | u64 | none | Unix seconds. Requests arriving at or after this answer 404. |
+
+Env overrides reach top-level fields only, and only under the local config provider. `IGGY_CONNECTORS_SOURCE_<KEY>_PLUGIN_CONFIG_<FIELD>` sets one field of this table; the suffix is taken whole, so a nested attempt such as `..._ENDPOINTS_0_AUTH_SECRET` becomes the flat key `endpoints_0_auth_secret` and is ignored. Endpoint secrets therefore stay in TOML or go through the management API.
+
+Values are coerced before they are deserialized: `true`/`false` become booleans and anything that parses as a number becomes one. So `..._INSTANCE_NAME=42` or a numeric `..._TOPIC_PATH` hands a JSON number to a string field and fails the whole configuration parse, with an error that does not name the field. Quote such values into non-numeric form, or set them in TOML.
+
+`HttpSourceConfig` deliberately does not implement `Serialize`, so this connector cannot write a credential out by accident. That does **not** protect the values in your TOML: the runtime keeps plugin configuration as raw JSON and serves it verbatim from `GET /sources/{key}/configs/plugin` (and inside `/configs` and `/configs/active`), so anyone who can reach the runtime's control API can read every secret configured here. Treat that API as privileged. (`/stats` carries no plugin configuration.)
+
+`http_sink` calls its equivalent knob `max_payload_size_bytes`. The names differ deliberately: the sink's bounds an outgoing payload, this one bounds an accepted request.
+
+## Routing
+
+Two kinds of path, both `POST`:
+
+```text
+POST /topics/{topic_path}   named path, one per instance, guarded by auth_bearer_token
+POST /e/{endpoint_id}       secret path, many per instance, each with its own auth
+```
+
+A secret-path URL is itself the credential: 32 hex characters is 128 bits of entropy, the same model as a Slack webhook URL. Treat these URLs as secrets and prefer adding an HMAC on top for providers that support one.
+
+Paths must be unique across every instance sharing a listener. Two instances claiming the same `topic_path` or the same `endpoint_id` fail the second instance's `open()` rather than letting one silently take the other's traffic.
+
+## Request and response contract
+
+```text
+POST /e/a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d
+X-Hub-Signature-256: sha256=...
+Content-Type: application/json
+
+{"event": "push", "repository": "apache/iggy"}
+```
+
+| Status | Condition | Body |
+| ------ | --------- | ---- |
+| 200 | Accepted into the bridge | `{"status":"queued"}` |
+| 401 | Bearer or HMAC validation failed | `{"error":"unauthorized"}` |
+| 404 | Unknown path, or a revoked or expired endpoint | `{"error":"not found"}` |
+| 400 | Malformed request body, e.g. the client reset mid-send | `{"error":"bad request"}` |
+| 413 | Body over `max_body_size_bytes` | `{"error":"payload too large"}` |
+| 429 | Bridge full | `{"error":"too many requests"}` plus `Retry-After: 1` |
+| 503 | `GET /health` when any instance on the listener has stopped polling, or a POST whose instance bridge has no receiver | `{"status":"unavailable"}` or `{"error":"service unavailable"}` |
+
+Revoked and expired endpoints both answer 404 rather than 410 or 403 on purpose: a leaked URL must not be usable to confirm that it was once live. The lookup runs before any credential is checked, so anything other than 404 would answer that question for an unauthenticated caller. Error bodies carry no internals; diagnostics live on the admin listener.
+
+`GET /health` on the public listener answers 200 only while every instance on it is serving, and 503 otherwise, which is what a load balancer should watch. It is deliberately all rather than any: one address fronts every instance sharing the listener, so a sibling whose poll task has stopped would otherwise keep receiving traffic into a bridge nothing drains. Shedding the healthy siblings costs availability the sender recovers by retrying, where the alternative loses requests already answered 200.
+
+HMAC signatures are validated over the raw request body exactly as received, never over a re-serialized form, and compared in constant time.
+
+The supported shape is a hex digest of the body behind a fixed prefix, which covers GitHub (`X-Hub-Signature-256: sha256=<hex>`) and most generic partner webhooks. Set `hmac_prefix = ""` for a bare hex signature.
+
+Providers that sign a composed string rather than the body alone are **not** supported in v1. Stripe signs `{timestamp}.{body}` and packs it into `Stripe-Signature: t=...,v1=...`; Twilio signs the URL plus sorted form parameters as base64. For those, use `bearer` or an endpoint with `auth_type = "none"`, forward the signature header, and verify it downstream.
+
+## Message headers
+
+With `include_http_metadata = true` each message carries:
+
+| Header | Value |
+| ------ | ----- |
+| `iggy_source_instance` | `instance_name`, or the connector id if unset |
+| `iggy_http_remote_addr` | TCP peer address. Behind the load balancer this README recommends, that is the proxy, not the sender; forward `X-Forwarded-For` to see the original client |
+| `iggy_http_received_at` | Accept time, microseconds since the Unix epoch |
+
+Anything listed in `forward_headers` is copied alongside, under its own name. Iggy rejects header values over 255 bytes, and real values such as `User-Agent` routinely exceed that, so forwarded values are truncated to fit rather than failing the message. Truncations and drops are counted in `http_source_headers_clamped_total` and `http_source_headers_dropped_total`.
+
+Forwarding the provider's delivery id is the recommended default, because it is the dedup key a consumer needs to close the duplicate window described above.
+
+## Sharing one listener
+
+The first instance to open binds both ports. Later instances validate their configuration against the running listener and join it. `admin_listen_addr`, `max_body_size_bytes`, and `management_token` must agree; a mismatch fails that instance's `open()` with a message naming the field, rather than silently handing it a listener its configuration does not describe.
+
+`listen_addr` is not validated that way, because it is what groups instances onto a listener in the first place. Two spellings of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two groups, so the second instance tries to bind a port the first already holds and fails with an address-in-use error naming that field. Instances meant to share a listener must spell `listen_addr` identically.
+
+`instance_name` must also be unique on the listener, since it is how the management API addresses an instance and how every metric series is labelled. Instances that leave it unset get their distinct numeric plugin id, so they cannot collide. It cannot be `unrouted`, which is reserved for the series counting requests that matched no route; `open()` fails naming the field.
+
+Closing an instance deregisters its routes immediately, so its paths answer 404 while its siblings keep serving. The last instance to close shuts both listeners down gracefully and releases the ports, which the runtime's stop-then-start restart flow depends on.
+
+The registry is per process. Several runtime processes behind a load balancer will not converge on dynamically registered endpoints; that is a fleet-coordination problem left to a future version. Single-process, multi-instance deployments are consistent by construction.
+
+## Dynamic endpoint management
+
+Set `management_token` to enable `/admin/endpoints` on the admin listener. Without it the API is not mounted at all and every path under it answers 404. Every call needs `Authorization: Bearer <management_token>`.
+
+```text
+POST   /admin/endpoints          register, id generated server-side  -> 201
+GET    /admin/endpoints          list every endpoint, secrets omitted -> 200
+GET    /admin/endpoints/{id}     one endpoint                         -> 200
+PATCH  /admin/endpoints/{id}     rotate auth_secret in place          -> 200
+DELETE /admin/endpoints/{id}     revoke                               -> 202
+```
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/admin/endpoints \
+  -H 'Authorization: Bearer replace_with_admin_token' \
+  -H 'Content-Type: application/json' \
+  -d '{"instance":"http_github","auth_type":"hmac-sha256","auth_secret":"whsec_new"}'
+# {"endpoint_id":"9f2c...","path":"/e/9f2c..."}
+```
+
+Rotation deliberately keeps the path: a webhook sender configures the URL once, so changing the shared secret must not force it to be reconfigured. It applies to dynamic endpoints only: a static endpoint's secret lives in TOML, so rotating one answers 409 and points you at the file, because restoring prefers TOML and would silently revert the change on the next restart.
+
+| Status | Condition |

Review Comment:
   Three reachable statuses are missing: 415 (`management.rs:110`, `:239`, `:316`, missing or wrong content type), 422 (`deny_unknown_fields` or a type error, pinned at `management.rs:876-880`), and 507 (`management.rs:182-186`) - the last being the refusal an operator actually meets at the new `MAX_ENDPOINTS` ceiling, currently documented only in prose at :322.
   
   The 400 row also omits `auth_type: none` supplied with a secret (`management.rs:124`) and the 256-byte `reason` cap (`:322`); the 409 row omits rotating a `none` endpoint and rotating an expired one (`:259-266`).



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2202 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Counted after the routes are gone, which narrows the window but does
+    // not close it: a handler that already loaded the old table can still
+    // enqueue after this read. The SDK stops the poll task before close(), so
+    // whatever is queued here is unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {

Review Comment:
   No `.fallback` here, so an unmatched path answers axum's empty-body 404 and a wrong method an undocumented 405, while README:175 promises `{"error":"not found"}` for "Unknown path". The crate's own test at `management.rs:654-658` pins the empty body, so the two are already inconsistent on purpose in one place and by accident in the other. A client parsing `error` on every 4xx breaks on exactly the response a mistyped path produces.
   
   Fix: `.fallback` returning `error_response`, or document both axum-generated statuses in the table.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,778 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked
+                && endpoint.auth_type.hmac_algorithm().is_some()
+                && HeaderName::from_str(&endpoint.hmac_header).is_err()
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id} with hmac_header '{}', which is not a valid HTTP header name; every signed request to it will be rejected until it is re-registered",
+                    endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {

Review Comment:
   This arm inserts the persisted `Endpoint` verbatim, keeping its `origin`, while only `endpoint_id` is forced from the key (:120). So a `Dynamic` tombstone can be the entry that outranks a TOML block declaring the same id - and `reclaimable_tombstones` (:233-251) evicts exactly the `Dynamic` ones, after which the next restart serves that TOML endpoint and its secret again. That contradicts :204-208, which is the argument that makes reclamation safe in the first place.
   
   Fix: force `origin = EndpointOrigin::Static` in this arm when TOML declares the key. Occupied arm only - doing the same in the Vacant arm would make genuine dynamic tombstones unreclaimable and brick registration at the ceiling.



##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,778 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use axum::http::HeaderName;
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use std::str::FromStr;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::EndpointId;
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // Registration rejects a malformed `hmac_header`, but state written
+            // by an older build, or edited by hand, can still carry one. Such an
+            // endpoint 401s every signed request forever because `HeaderMap::get`
+            // answers `None` for a name it cannot parse, and nothing else would
+            // ever say why. Restoring it anyway is deliberate: refusing to start
+            // over one bad entry would take the whole instance down with it.
+            if !revoked

Review Comment:
   This warns on an unparsable `hmac_header` and never checks the secret, and the two adjacent inputs fail in opposite directions. `auth_secret: None` yields `hmac_key: None` at `routes.rs:260-264`, so `authorize` fails closed (`server.rs:907`). `Some("")` builds a real `hmac::Key` over an empty secret, which anyone holding the URL can sign for. `is_usable_secret` guards `validate()` and `register_endpoint`, but not this path - the one deliberately made fail-closed.
   
   Reachable without a hand-edited file: an older build of this plugin, or whatever backs the runtime's state store.
   
   Fix: gate the `hmac_key` construction at `routes.rs:260-264` on `is_usable_secret`, so `authorize` takes the fail-closed arm it already has. Not a demote and not a tombstone - `rotate_secret` refuses a non-active endpoint, so tombstoning here would take away the operator's only recovery.



##########
.claude/skills/connector-testing/SKILL.md:
##########
@@ -54,6 +54,33 @@ fn given_payload_json_should_serialize_correctly() { ... }
 
 You may **omit one part** when the test is small (`given_X_should_Y` instead of full `given_X_when_Y_should_Z`), but **stay consistent within a file**. Imperative `test_foo` / `does_bar` names are not the convention here.
 
+### Prove a test can fail, before trusting it

Review Comment:
   This new section sits 80 lines above a rule that contradicts the connector it was written for. The mandatory canonical tests at :113-145 still require `given_invalid_state_should_start_fresh` with `/* assert default state */` (:140-143) - the fail-open restore you called critical, and which `state.rs:98-105` now deliberately inverts by failing `open()` instead. A source author following this file reproduces the defect, and the new prove-it-can-fail guidance will not catch it, because that test passes either way.
   
   Fix: mandate fail-closed where restored state gates access, and cite `http_source::state::restore` as the exemplar.
   
   Four more rules across the two skill files now contradict this PR's own text, so they are probably one pass rather than five patches: `connector-source` pitfalls 4, 6 and 8 restate rules this PR replaced (pitfall 6's blanket `std::sync::Mutex` ban included, which CLAUDE.md rule 11 scopes to locks held across `.await`, and which this connector was asked to break); `:90`'s unqualified "sleep first" against a listener source that blocks on `recv().await`; and `:103`'s `id` guidance, which is what produced the wire-id-0 defect fixed in code only.



##########
core/connectors/sources/http_source/README.md:
##########
@@ -0,0 +1,340 @@
+# HTTP Source Connector (Webhook Gateway)
+
+The HTTP source connector turns Apache Iggy into a webhook receiver. It runs an embedded HTTP server, accepts `POST` bodies on authenticated paths, and produces them to the instance's configured stream and topic as raw bytes.
+
+Every instance of this plugin shares one listener, so a single port can serve many providers, each routed to its own topic.
+
+## Delivery semantics (read this first)
+
+> **Delivery guarantee: best-effort.** HTTP 200 means "accepted into the connector's in-memory buffer", not "durably stored in Iggy". This is weaker than at-most-once: a message can be lost after acknowledgment, with no record beyond a log line and a metric.
+
+Loss windows, explicitly:
+
+1. **Process crash** between HTTP 200 and the producer send. Buffered messages are volatile.
+2. **Producer failure.** Narrowed by #3855, which gave sources a delivery result. The runtime NACKs a batch it could not send, or whose state it could not persist, and neither is abandoned here: a message batch is held and replayed on the next `poll()`, and a state-only batch re-arms the flush so the mutation is handed out again. Answering 200 already told the sender this gateway owns the event, and the only honest way to shed load is the 429 handlers return once the bridge fills.
+3. **Shutdown.** Narrowed by #3321, which closes the plugin before tearing down the forwarding channel so in-flight batches drain. Messages still in the bridge when the poll task stops are lost; the connector logs the count and increments `http_source_dropped_on_close_total`.
+4. **Poll task stopped by the SDK.** A source is stopped after five consecutive NACKs, roughly 1.5s of backoff plus five send rounds, so a broker outage longer than that ends the poll task while the listener keeps accepting. Whatever the bridge holds is then lost on the next restart, and the stop is unobservable: the runtime's forwarding loop stays parked, so the source keeps being counted as running while nothing polls. Tracked in #3941.
+
+What mitigates this in practice is the caller: webhook senders such as GitHub, Stripe, and Twilio retry on timeout and 5xx, so the sender side is at-least-once up to the moment this connector returns 200. The connector's job is to make the post-200 window as small and as observable as possible.
+
+**Duplicates are also possible.** The same retries that mitigate loss create a duplicate window:
+
+1. A caller times out after the connector enqueued the message but before the 200 reached it, retries, and the payload lands twice.
+2. A load balancer or proxy retries a POST after a hiccup downstream of a successful enqueue.
+3. A NACK does not mean the batch never landed. The runtime NACKs a batch it sent but whose state it could not persist, and the SDK NACKs on its own result timeout while the send may still have succeeded, so the replay on the next `poll()` re-sends messages that are already on the topic. This is the window the connector itself creates, and it is the price of not dropping post-200 data.
+
+So the guarantee is best-effort in both directions: no silent-loss guarantee and no dedup guarantee.
+
+Every accepted request is given a random 128-bit message id at accept time, and a batch replayed after a NACK carries the same id it had the first time. That closes the third window above for any consumer that dedupes on the Iggy message id.
+
+It does **not** close the first two. A sender that retries because it never saw the 200 produces a genuinely new request, which gets a new id. For those, dedupe on the provider's delivery id (`X-GitHub-Delivery`, `svix-id`, Stripe's `event.id` in the body), which is why forwarding those headers is the default recommendation.
+
+Stronger guarantees need an SDK change, not a connector change: at-least-once by construction requires the runtime to hand the connector a producer handle so it can await the send before answering 200. See #3039.
+
+## Configuration
+
+Two instances sharing one listener, each routing to its own topic. Each block is a separate connector configuration file.
+
+```toml
+# instance 1: GitHub webhooks -> webhooks/github_events
+type = "source"
+key = "http_github"
+enabled = true
+version = 0
+name = "HTTP source (GitHub)"
+path = "../../target/release/libiggy_connector_http_source"
+verbose = false
+
+[[streams]]
+stream = "webhooks"
+topic = "github_events"
+schema = "raw"
+batch_length = 100
+linger_time = "5ms"
+
+[plugin_config]
+# Loopback so a copied snippet cannot expose a port. Production wants 0.0.0.0
+# behind a load balancer, with TLS terminated in front of it. The runtime's env
+# overrides can supply `auth_bearer_token` and `management_token`, but they
+# reach top-level fields only: an endpoint's `auth_secret` stays in this file
+# or is registered through the management API. See Options below.
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_github"
+topic_path = "github_events"
+auth_bearer_token = "replace_with_secret_token"
+management_token = "replace_with_admin_token"
+max_body_size_bytes = 1048576
+buffer_capacity = 10000
+max_batch_size = 500
+include_http_metadata = true
+forward_headers = ["X-GitHub-Delivery", "X-Request-ID"]
+
+[[plugin_config.endpoints]]
+endpoint_id = "a3f8c2e1b9d04f7a8e6c1d2b3a4f5e6d"
+auth_type = "hmac-sha256"
+auth_secret = "whsec_github_example"
+hmac_header = "X-Hub-Signature-256"
+hmac_prefix = "sha256="
+```
+
+```toml
+# instance 2: partner webhooks -> webhooks/partner_events, joining the same listener
+type = "source"
+key = "http_partner"
+enabled = true
+version = 0
+name = "HTTP source (partner)"
+path = "../../target/release/libiggy_connector_http_source"
+
+[[streams]]
+stream = "webhooks"
+topic = "partner_events"
+schema = "raw"
+
+[plugin_config]
+listen_addr = "127.0.0.1:9090"
+admin_listen_addr = "127.0.0.1:9091"
+instance_name = "http_partner"
+management_token = "replace_with_admin_token"
+# no topic_path: this instance serves secret-path endpoints only
+
+[[plugin_config.endpoints]]
+endpoint_id = "0b7d9e2f4a6c8e1d3b5f7a9c2e4d6f81"
+auth_type = "bearer"
+auth_secret = "partner-token"
+```
+
+The stream's `schema` **must be `raw`**. This connector always produces raw bodies; with `schema = "json"` the runtime's encoder rejects every message, which counts as a processing error and becomes a NACK rather than a drop.
+
+The batch is then replayed on every poll and the SDK stops the poll task after five consecutive NACKs, while the listener keeps answering 200. The connector cannot guard against this itself: `schema` lives under `[[streams]]` and the plugin only ever receives `[plugin_config]`, so nothing in `open()` can see it.
+
+### Options
+
+| Option | Type | Default | Description |

Review Comment:
   Three enforced ceilings are absent from this table: `buffer_capacity` 1_000_000, `max_batch_size` 100_000 and `max_body_size_bytes` 64 MiB (`lib.rs:67-72`, enforced at `:533-550`). An operator who sets a 100 MB body cap gets a hard `open()` failure with nothing in the docs to explain it. A Max column covers all three.



##########
core/connectors/sources/http_source/src/management.rs:
##########
@@ -0,0 +1,1288 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The endpoint management API, served on the admin listener only.
+//!
+//! The operations here are the ones a TOML edit plus a restart is the wrong
+//! tool for: revoking a compromised endpoint is time-critical, and a platform
+//! provisioning a webhook URL per tenant is inherently programmatic.
+//!
+//! Disabled unless `management_token` is set, and never reachable from the
+//! public listener. Mutations become durable on the next successful poll, so
+//! a response here means "accepted", not "written"; `GET /admin/endpoints`
+//! reports `submitted` per endpoint for callers that need the difference,
+//! though the underlying flush covers the whole registry at once.
+
+use axum::extract::rejection::JsonRejection;
+use axum::extract::{Path, Request, State};
+use axum::http::{HeaderMap, HeaderName, StatusCode};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use rand::RngExt;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+use crate::auth::{is_usable_secret, validate_bearer};
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::server::{ServerState, bearer_header, error_response, refresh_routes};
+use crate::state::{InsertOutcome, MAX_ENDPOINTS};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, SharedState};
+
+/// Bytes of entropy behind a generated endpoint id. The URL is the bearer
+/// token for a secret-path endpoint, so it carries the whole secret.
+const ENDPOINT_ID_BYTES: usize = 16;
+
+/// A revoke reason rides the tombstone, and tombstones are never evicted,
+/// so an uncapped one is an authenticated caller writing to the state file
+/// without limit.
+const MAX_REVOKE_REASON_LEN: usize = 256;
+
+pub(crate) fn router(state: Arc<ServerState>) -> Router<Arc<ServerState>> {
+    if state.management_token.is_none() {
+        info!(
+            "Dynamic endpoint management is disabled for the {CONNECTOR_NAME} listener on {}: no management_token is configured",
+            state.listen_addr
+        );
+        return Router::new();
+    }
+    info!(
+        "Enabled dynamic endpoint management for the {CONNECTOR_NAME} listener on {}",
+        state.listen_addr
+    );
+    Router::new()
+        .route(
+            "/admin/endpoints",
+            post(register_endpoint).get(list_endpoints),
+        )
+        .route(
+            "/admin/endpoints/{endpoint_id}",
+            get(get_endpoint)
+                .patch(rotate_secret)
+                .delete(revoke_endpoint),
+        )
+        // The guard is a layer, not a line in each handler, because axum runs
+        // every extractor before the handler body. Checking inside the handler
+        // still read and parsed an unauthenticated request's JSON first, which
+        // is not what the route tests below claim to prove.
+        .layer(middleware::from_fn_with_state(
+            Arc::clone(&state),
+            require_management_token,
+        ))
+}
+
+async fn require_management_token(
+    State(state): State<Arc<ServerState>>,
+    request: Request,
+    next: Next,
+) -> Response {
+    if let Some(response) = denied(&state, request.headers()) {
+        return response;
+    }
+    next.run(request).await
+}
+
+async fn register_endpoint(
+    State(state): State<Arc<ServerState>>,
+    body: Result<Json<RegisterRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+
+    let Some(instance) = state.instance(&request.instance) else {
+        return error_response(StatusCode::NOT_FOUND, "unknown instance");
+    };
+    if request.auth_type != EndpointAuthType::None && !is_usable_secret(&request.auth_secret) {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "a non-empty auth_secret is required",
+        );
+    }
+    // `authorize` never reads a secret for an unauthenticated endpoint, so
+    // accepting one only persists a credential nothing will ever check.
+    if request.auth_type == EndpointAuthType::None && request.auth_secret.is_some() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "auth_type 'none' takes no auth_secret",
+        );
+    }
+    if request
+        .expires_at
+        .is_some_and(|expires_at| expires_at <= unix_now_seconds())
+    {
+        return error_response(StatusCode::BAD_REQUEST, "expires_at is already past");
+    }
+    // The same check the static config gets. `HeaderMap::get` answers `None`
+    // for a name it cannot parse rather than failing, so an endpoint
+    // registered with a malformed one would 401 every signed request forever,
+    // survive a restart, and give no clue why. Recovery would mean revoking,
+    // re-registering, and reconfiguring the sender.
+    if HeaderName::from_str(&request.hmac_header).is_err() {
+        return error_response(
+            StatusCode::BAD_REQUEST,
+            "hmac_header is not a valid HTTP header name",
+        );
+    }
+
+    let endpoint_id = generate_endpoint_id();
+    let endpoint = Endpoint {
+        endpoint_id: endpoint_id.clone(),
+        auth_type: request.auth_type,
+        auth_secret: request.auth_secret,
+        hmac_header: request.hmac_header,
+        hmac_prefix: request.hmac_prefix,
+        expires_at: request.expires_at,
+        origin: EndpointOrigin::Dynamic,
+        state: EndpointState::Active,
+    };
+
+    let mut outcome = InsertOutcome::Collision;
+    instance.mutate_registry(|registry| {
+        outcome = registry.try_insert(endpoint);
+        outcome == InsertOutcome::Inserted
+    });
+    match outcome {
+        InsertOutcome::Inserted => {}
+        InsertOutcome::Collision => {
+            // 128 bits of entropy makes this unreachable in practice; refusing
+            // to overwrite is what keeps it from silently retargeting live
+            // traffic.
+            warn!(
+                "Generated a colliding endpoint id for {CONNECTOR_NAME} connector ID: {instance_id}, refusing the registration",
+                instance_id = instance.id
+            );
+            return error_response(StatusCode::CONFLICT, "endpoint id collision");
+        }
+        InsertOutcome::Full => {
+            warn!(
+                "Registry for {CONNECTOR_NAME} connector ID: {instance_id} holds {MAX_ENDPOINTS} endpoints with no reclaimable tombstones, refusing the registration",
+                instance_id = instance.id
+            );
+            return error_response(
+                StatusCode::INSUFFICIENT_STORAGE,
+                "endpoint registry is full",
+            );
+        }
+    }
+    warn_if_poll_stopped(&instance, "Registered", endpoint_id.as_str());
+    if let Some(failure) = republish(&state).await {
+        // Undo the insert. Left in place it would be persisted on the next
+        // flush and come back live after a restart, despite the caller having
+        // been told the registration failed.
+        if !instance.mutate_registry(|registry| registry.remove(endpoint_id.as_str())) {
+            error!(
+                "Failed to roll back endpoint {} on {CONNECTOR_NAME} connector ID: {}; it may be persisted and served after a restart despite this registration failing",
+                endpoint_id.log_prefix(),
+                instance.id
+            );
+        }
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        // The instance closed while we were mutating it. Its registry is no
+        // longer polled or projected, so the URL we would hand back is dead.
+        // No rollback: that registry is already unreachable, and the poll task
+        // that could have persisted it is stopped.
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    // Logged by prefix only: the full id is the credential for a secret-path
+    // endpoint, and process logs reach a far wider audience than the state
+    // directory the README scopes secrets to.
+    info!(
+        "Registered endpoint {} for {CONNECTOR_NAME} connector ID: {}",
+        endpoint_id.log_prefix(),
+        instance.id
+    );
+    (
+        StatusCode::CREATED,
+        Json(RegisteredEndpoint {
+            path: format!("/e/{endpoint_id}"),
+            endpoint_id,
+        }),
+    )
+        .into_response()
+}
+
+/// Replaces an endpoint's secret without changing its URL.
+///
+/// Deliberate: a webhook sender configures the URL once, so rotating the
+/// shared secret must not force it to be reconfigured.
+async fn rotate_secret(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Json<RotateRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Json(request) = match body {
+        Ok(body) => body,
+        Err(rejection) => return error_response(rejection.status(), "invalid request body"),
+    };
+    if request.auth_secret.expose_secret().is_empty() {
+        // An empty HMAC key validates any signature the holder of the URL can
+        // compute, so rotating to one silently removes the second factor.
+        return error_response(StatusCode::BAD_REQUEST, "auth_secret must not be empty");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    let rejection = instance
+        .registry()
+        .endpoint(&endpoint_id)
+        .and_then(|endpoint| {
+            if endpoint.origin == EndpointOrigin::Static {
+                // Restoring prefers TOML over any still-active persisted
+                // entry, so a rotated static secret would silently revert on
+                // the next restart and the operator would believe a leaked
+                // secret had been replaced.
+                Some("a static endpoint's secret lives in TOML; edit auth_secret there and restart the instance")
+            } else if endpoint.auth_type == EndpointAuthType::None {
+                // Nothing reads it, so a 200 would report a rotation that
+                // changes no behaviour while persisting the new secret.
+                Some("auth_type 'none' has no secret to rotate")
+            } else if endpoint.is_expired(unix_now_seconds()) {
+                // is_active() is state only, so without this an expired
+                // endpoint answers 200 for a path that already 404s.
+                Some("endpoint has expired; register a replacement")
+            } else {
+                None
+            }
+        });
+    if let Some(message) = rejection {
+        return error_response(StatusCode::CONFLICT, message);
+    }
+
+    let rotated = instance.mutate_registry(|registry| {
+        let Some(endpoint) = registry.endpoint_mut(&endpoint_id) else {
+            return false;
+        };
+        if !endpoint.is_active() {
+            return false;
+        }
+        endpoint.auth_secret = Some(request.auth_secret.clone());
+        true
+    });
+    if !rotated {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    warn_if_poll_stopped(&instance, "Rotated", &endpoint_id);
+    info!(
+        "Rotated the secret for endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    summary_response(&instance, &endpoint_id)
+}
+
+async fn revoke_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    body: Result<Option<Json<RevokeRequest>>, JsonRejection>,
+) -> Response {
+    // `Option<Json<_>>` alone yields `None` only when there is no content
+    // type; malformed JSON or the wrong one came back as axum's plain-text
+    // rejection, which is neither this API's `{"error":..}` shape nor
+    // documented anywhere.
+    let body = match body {
+        Ok(body) => body,
+        Err(rejection) => {
+            return error_response(rejection.status(), "invalid request body");
+        }
+    };
+    let reason = body
+        .and_then(|Json(request)| request.reason)
+        .unwrap_or_else(|| "unspecified".to_string());
+    if reason.len() > MAX_REVOKE_REASON_LEN {
+        return error_response(StatusCode::BAD_REQUEST, "reason is longer than 256 bytes");
+    }
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+
+    let revoked = instance
+        .mutate_registry(|registry| registry.revoke(&endpoint_id, reason, unix_now_seconds()));
+    if !revoked {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    }
+    if let Some(failure) = republish_or_close(&state).await {
+        return failure;
+    }
+    // Most important here of the three: a revocation reported 204 but landed
+    // on a departed instance is never persisted, so the compromised endpoint
+    // comes back after the restart the operator is probably about to do.
+    if !still_joined(&state, &instance) {
+        return error_response(StatusCode::SERVICE_UNAVAILABLE, "instance is closing");
+    }
+
+    warn_if_poll_stopped(&instance, "Revoked", &endpoint_id);
+    info!(
+        "Revoked endpoint {} on {CONNECTOR_NAME} connector ID: {}",
+        EndpointId::log_prefix_of(&endpoint_id),
+        instance.id
+    );
+    // 202, not 204. The tombstone is live in the route table before this
+    // returns, so the endpoint stops serving immediately, but it reaches the
+    // runtime only on a later `poll()`, and the flag it flips clears when the
+    // state leaves the plugin rather than when the runtime writes it, so
+    // waiting on it would not prove durability either.
+    // `GET /admin/endpoints/{id}` is where an operator watches for it.
+    StatusCode::ACCEPTED.into_response()
+}
+
+async fn list_endpoints(State(state): State<Arc<ServerState>>) -> Response {
+    let endpoints: Vec<EndpointSummary> = state
+        .instances()
+        .iter()
+        .flat_map(|instance| {
+            instance
+                .registry()
+                .endpoints()
+                .map(|endpoint| EndpointSummary::new(instance, endpoint))
+                .collect::<Vec<_>>()
+        })
+        .collect();
+    Json(endpoints).into_response()
+}
+
+async fn get_endpoint(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+) -> Response {
+    let Some(instance) = owner_of(&state, &endpoint_id) else {
+        return error_response(StatusCode::NOT_FOUND, "not found");
+    };
+    summary_response(&instance, &endpoint_id)
+}
+
+/// Guards every management call with the shared token, answering with the
+/// rejection to send when the caller may not proceed.
+///
+/// The token is required rather than optional here: the router is only
+/// mounted when one is configured, so reaching a handler without one would
+/// mean the listener is serving an endpoint it never meant to expose.
+fn denied(state: &ServerState, request_headers: &HeaderMap) -> Option<Response> {
+    let Some(expected) = &state.management_token else {
+        return Some(error_response(StatusCode::NOT_FOUND, "not found"));
+    };
+    // The same comparison the webhook paths use, rather than a second
+    // hand-rolled one: an extra `SecretString` was allocated only to be
+    // compared and dropped.
+    if validate_bearer(bearer_header(request_headers), expected) {
+        return None;
+    }
+    Some(error_response(StatusCode::UNAUTHORIZED, "unauthorized"))
+}
+
+fn owner_of(state: &ServerState, endpoint_id: &str) -> Option<Arc<SharedState>> {
+    state
+        .instances()
+        .into_iter()
+        .find(|instance| instance.registry().endpoint(endpoint_id).is_some())
+}
+
+/// Warns when a mutation landed on an instance whose poll task looks stopped.
+///
+/// [`still_joined`] proves only that the instance is registered. The SDK stops
+/// the poll task after five consecutive NACKs without calling `close()`, so an
+/// instance can stay registered and keep answering 201 and 202 for changes
+/// nothing will ever carry to the runtime. `/admin/health` reports the same
+/// signal as `poll_is_live`. See #3941.
+fn warn_if_poll_stopped(instance: &Arc<SharedState>, action: &str, endpoint_id: &str) {
+    if instance.poll_is_live(unix_now_seconds()) {
+        return;
+    }
+    warn!(
+        "{action} endpoint {} on {CONNECTOR_NAME} connector ID: {} while its poll task looks stopped; the change is in memory but nothing is carrying it to the runtime",
+        EndpointId::log_prefix_of(endpoint_id),
+        instance.id
+    );
+}
+
+/// Whether the instance a handler resolved earlier is still the one joined
+/// under that name. A handler awaits between resolving and mutating, and an
+/// instance can close in between - the mutation would then land on a registry
+/// nobody polls and the caller would be told it succeeded.
+fn still_joined(state: &ServerState, instance: &Arc<SharedState>) -> bool {
+    state
+        .instance(&instance.instance_name)
+        .is_some_and(|current| Arc::ptr_eq(&current, instance))
+}
+
+/// Projects the mutated registry into the shared route table.
+///
+/// A failure here leaves the registry ahead of the routes, so it answers 500
+/// rather than pretending the endpoint is live.
+async fn republish(state: &ServerState) -> Option<Response> {
+    let Err(error) = refresh_routes(&state.listen_addr).await else {
+        return None;
+    };
+    warn!(
+        "Failed to republish {CONNECTOR_NAME} routes on {}. {error}",
+        state.listen_addr
+    );
+    Some(error_response(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        "route update failed",
+    ))
+}
+
+/// Republish for a mutation that takes access AWAY. If the table cannot be
+/// rebuilt, the old one is still serving the endpoint the operator just
+/// revoked or re-keyed, so serve nothing rather than a credential they
+/// believe is dead.
+async fn republish_or_close(state: &ServerState) -> Option<Response> {
+    let failure = republish(state).await?;
+    state.serve_nothing();
+    Some(failure)
+}
+
+fn summary_response(instance: &Arc<SharedState>, endpoint_id: &str) -> Response {
+    let registry = instance.registry();
+    match registry.endpoint(endpoint_id) {
+        Some(endpoint) => Json(EndpointSummary::new(instance, endpoint)).into_response(),
+        None => error_response(StatusCode::NOT_FOUND, "not found"),
+    }
+}
+
+fn generate_endpoint_id() -> EndpointId {
+    let bytes: [u8; ENDPOINT_ID_BYTES] = rand::rng().random();
+    hex::encode(bytes)
+        .parse()
+        .expect("hex of 16 bytes is 32 lowercase hex characters")
+}
+
+// The three request bodies below reject unknown fields. Unlike the plugin
+// config, they never carry the runtime's flat env overrides, so a rejected
+// unknown field is a caller typo and nothing else.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RegisterRequest {
+    instance: String,
+    #[serde(default)]
+    auth_type: EndpointAuthType,
+    #[serde(default)]
+    auth_secret: Option<SecretString>,

Review Comment:
   This field, `hmac_header` (:493), `hmac_prefix` (:495) and `RotateRequest::auth_secret` (:503) have no length bound. The only cap is `DefaultBodyLimit::max(max_body_size_bytes)` (`server.rs:539`), up to 64 MiB, times `MAX_ENDPOINTS`. `reason` was capped at 256 bytes for less, and unlike `reason` these ride active entries that are deep-cloned on every `mutate_registry` (`lib.rs:259`) and re-serialized whole on every flush (`state.rs:312`), so README:316's "roughly a hundred bytes" stops holding.
   
   It also reaches the public listener: `to_connector_state` runs synchronously on the poll task that is the bridge's only drainer, so a bloated registry stalls the drain and comes out as 429s on the accept path, with no metric tying the two together.
   
   Fix: cap them on register and rotate only, never in `restore` - :98-105 turns a restore failure into a hard `open()` failure, so a cap there would take an instance down over one over-long stored value. A `warn!` there, matching the `hmac_header` treatment at :128.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2002 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {

Review Comment:
   `EndpointRegistry` lives in a private module but leaks through this signature on a crate-root `pub struct`, which silences `dead_code` for every method on it. `unreachable_pub` is allow-by-default, so workspace `warnings = "deny"` never fires. Confirmed on a standalone repro: a `pub` method unused inside a private module warns as expected, and adding a single crate-root `pub fn` returning that module's type silences it entirely.
   
   It is already hiding one: `state.rs:195` `insert` has no non-test caller, while its doc says it is "kept for callers that only care whether the registry changed". Nothing in the workspace links this crate as a lib, and `lib.rs` exposes 17 top-level `pub` items where the sibling sources expose 1 to 4.
   
   Fix: `pub(crate)` on `SharedState`, `registry()` and the registry API, delete `insert`, and let the tests assert on `try_insert`.



##########
core/connectors/sources/http_source/src/lib.rs:
##########
@@ -0,0 +1,2002 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod auth;
+mod management;
+mod metrics;
+mod routes;
+mod server;
+mod state;
+mod types;
+
+use arc_swap::{ArcSwap, Guard};
+use async_trait::async_trait;
+use axum::http::{HeaderName, header};
+use iggy_common::HeaderKey;
+use iggy_connector_sdk::{
+    ConnectorState, Error, ProducedMessage, ProducedMessages, Schema, Source, source,
+    source_connector,
+};
+use ring::hmac;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeSet;
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Mutex as StdMutex, PoisonError};
+use std::time::Duration;
+use tokio::sync::{Mutex, Notify};
+use tracing::{debug, info, warn};
+
+use crate::server::{INSTANCE_HEADER, RECEIVED_AT_HEADER, REMOTE_ADDR_HEADER};
+use crate::state::EndpointRegistry;
+use crate::types::{EndpointId, QueuedMessage, unix_now_seconds};
+
+pub const CONNECTOR_NAME: &str = "HTTP source";
+
+pub const DEFAULT_ADMIN_LISTEN_ADDR: &str = "127.0.0.1:9091";
+pub const DEFAULT_MAX_BODY_SIZE_BYTES: usize = 1024 * 1024;
+pub const DEFAULT_BUFFER_CAPACITY: usize = 10_000;
+pub const DEFAULT_MAX_BATCH_SIZE: usize = 500;
+/// Ceilings for the three sizing values, mirroring their `> 0` floors.
+///
+/// `buffer_capacity` is the dangerous one: crossfire asserts `bound <=
+/// u32::MAX` while building the ring and allocates every slot eagerly, each
+/// holding an inline `MaybeUninit<T>`, so a typo either panics or OOMs. That
+/// panic unwinds out of `iggy_source_open`, which is
+/// `extern "C"` with no `catch_unwind` around it, and takes down the whole
+/// connectors process along with every other plugin loaded into it. The ring
+/// is built in `new`, before the SDK ever calls `open`, so `validate` cannot
+/// be what protects it.
+pub const BUFFER_CAPACITY_LIMIT: usize = 1_000_000;
+/// Bounds the drain loop in `poll()`, which fills a `Vec` from the bridge
+/// until it hits this many messages. Nothing is allocated up front, so an
+/// oversized value costs a longer drain rather than a large empty buffer.
+pub const MAX_BATCH_SIZE_LIMIT: usize = 100_000;
+pub const MAX_BODY_SIZE_BYTES_LIMIT: usize = 64 * 1024 * 1024;
+
+pub const DEFAULT_HMAC_HEADER: &str = "X-Hub-Signature-256";
+pub const DEFAULT_HMAC_PREFIX: &str = "sha256=";
+
+/// How long after a poll returns the source still counts as live. Generous
+/// against the SDK's 30s batch-result timeout, which is the longest a healthy
+/// source sits between polls.
+const POLL_LIVENESS_SECONDS: u64 = 60;
+
+/// HTTP handler side of an instance's bridge. The pair comes from
+/// `bounded_async` because the `poll()` side needs `recv().await`; the handler
+/// side only ever `try_send`s.
+pub type MessageSender = crossfire::MAsyncTx<crossfire::mpsc::Array<QueuedMessage>>;
+
+/// `poll()` side of an instance's bridge.
+pub type MessageReceiver = crossfire::AsyncRx<crossfire::mpsc::Array<QueuedMessage>>;
+
+source_connector!(HttpSource);
+
+/// Webhook gateway source: accepts HTTP POST requests on a listener shared
+/// by every instance of this plugin and produces the raw bodies to the
+/// instance's configured stream/topic.
+#[derive(Debug)]
+pub struct HttpSource {
+    shared: Arc<SharedState>,
+    /// Deliberately not on [`SharedState`]: handlers hold that behind an `Arc`
+    /// for as long as the listener serves them, and a receiver reachable from
+    /// there would outlive the source it belongs to.
+    ///
+    /// The mutex only exists to make the single-consumer receiver `Sync`, as
+    /// [`Source`] requires. The runtime drives exactly one `poll()` at a time,
+    /// so it is never contended despite being held across the wait.
+    receiver: Mutex<MessageReceiver>,
+    /// Batch already handed to the runtime and not yet acknowledged.
+    ///
+    /// The runtime NACKs a batch it could not send, expecting the next `poll()`
+    /// to produce it again. Draining the bridge is destructive, so without this
+    /// the events would exist nowhere else and the NACK would be silent loss.
+    /// `std`, not `tokio`: the guard never crosses an `.await`, so the async
+    /// lock only added suspension points. One of them mattered - a shutdown
+    /// landing inside `stage()` could drop the batch there with nothing
+    /// counting it.
+    staged: StdMutex<Option<StagedBatch>>,
+    /// Whether the last `poll()` returned a state-only batch, which decides
+    /// which arm of the next poll's `select!` gets first refusal.
+    ///
+    /// Not on [`SharedState`]: it is bookkeeping for the single poll task, and
+    /// nothing a request handler can reach has any business reading it.
+    last_poll_was_state_only: AtomicBool,
+    /// Why the persisted registry could not be restored, if it could not be.
+    ///
+    /// Held rather than acted on in `new` so `open` can fail with it, which is
+    /// what puts it on the control API as `last_error`.
+    restore_error: Option<String>,
+}
+
+/// Takes the message the `select!` arm received and tops the batch up with
+/// whatever else is already queued, without waiting for more.
+///
+/// The SDK races `poll()` against its own shutdown watch, so blocking on
+/// `recv()` until traffic arrives is what keeps an idle gateway off the CPU;
+/// crossfire documents it as cancellation-safe. `recv` errs only once every
+/// sender is dropped and one lives in `SharedState`, which outlives the poll,
+/// so an error leaves the batch empty rather than needing an arm of its own.
+fn drain_bridge(
+    receiver: &MessageReceiver,
+    received: Result<QueuedMessage, crossfire::RecvError>,
+    max_batch_size: usize,
+    queued: &mut Vec<QueuedMessage>,
+) {
+    let Ok(message) = received else {
+        return;
+    };
+    queued.push(message);
+    while queued.len() < max_batch_size {
+        let Ok(message) = receiver.try_recv() else {
+            break;
+        };
+        queued.push(message);
+    }
+}
+
+/// Clears the in-flight marker however `poll()` ends, including cancellation.
+/// The SDK drops the poll future when it stops the task, so without a guard a
+/// stopped source would look permanently mid-poll.
+pub(crate) struct PollGuard<'a>(&'a SharedState);
+
+impl Drop for PollGuard<'_> {
+    fn drop(&mut self) {
+        // Timestamp first. `poll_is_live` reads the two as an unsynchronised
+        // pair, so clearing the flag first leaves a window where a reader sees
+        // "not polling" beside the *previous* timestamp. On the first return
+        // that previous value is the constructor's 0, which reads as an hour
+        // stale, and `/health` answers 503 for a source that is perfectly
+        // healthy. Writing this way the pair is only ever seen as live.
+        self.0
+            .last_poll_at
+            .store(unix_now_seconds(), Ordering::Release);
+        self.0.poll_active.store(false, Ordering::Release);
+    }
+}
+
+/// Unacknowledged batch, kept whole so a NACK can be re-polled verbatim.
+#[derive(Debug)]
+struct StagedBatch {
+    messages: Vec<QueuedMessage>,
+    /// Consecutive NACKs this batch has taken, for the retry policy below.
+    nacks: u32,
+}
+
+/// Everything an HTTP handler needs from one instance.
+///
+/// Handler tasks hold `Arc<SharedState>` and never `Arc<HttpSource>`: the SDK
+/// tears a source down with `Arc::try_unwrap`, so a stray clone of the source
+/// itself would turn `close()` into a leak.
+#[derive(Debug)]
+pub struct SharedState {
+    pub id: u32,
+    pub config: HttpSourceConfig,
+    pub sender: MessageSender,
+    /// Resolved once from `instance_name`, falling back to the connector ID.
+    pub instance_name: String,
+    /// Each configured request header paired with the Iggy header key it lands
+    /// under, resolved once so the request path neither parses nor validates.
+    pub(crate) forward_headers: Vec<(HeaderName, HeaderKey)>,
+    registry: ArcSwap<EndpointRegistry>,
+    registry_dirty: AtomicBool,
+    /// Mutations made since the last one the runtime acknowledged.
+    ///
+    /// The registry is handed over whole, so durability was never per-endpoint;
+    /// what an operator losing a shutdown needs is how many changes went with
+    /// it. Counting them on the instance costs two atomics instead of a flag on
+    /// every endpoint and a clone of the whole registry per flush.
+    pending_changes: AtomicUsize,
+    /// Mutations in the batch currently awaiting the runtime's verdict, so a
+    /// NACK can return them to `pending_changes` rather than lose the count.
+    handed_changes: AtomicUsize,
+    /// True while a `poll()` is in flight, including the long block on an idle
+    /// bridge. Cleared by a guard, so a cancelled poll clears it too, which is
+    /// what makes a stopped poll task observable.
+    poll_active: AtomicBool,
+    /// When the last `poll()` returned. Covers the gap between polls, where
+    /// the SDK is awaiting a batch result and nothing is in flight.
+    last_poll_at: AtomicU64,
+    /// Serializes registry writers, which are all control-plane. The request
+    /// path only ever loads the `ArcSwap` and never touches this.
+    registry_writer: StdMutex<()>,
+    /// Wakes `poll()` when a management mutation needs a state flush and no
+    /// webhook traffic would otherwise arrive to carry it.
+    ///
+    /// Shared so a refused flush can re-post the permit from a timer rather
+    /// than immediately; see [`SharedState::rearm_state_flush`].
+    pub state_flush: Arc<Notify>,
+    /// Consecutive state flushes the runtime has refused, which is what the
+    /// re-post backs off on.
+    state_flush_nacks: AtomicU32,
+}
+
+impl SharedState {
+    /// Wait-free snapshot of the registry. Requests do not come through here:
+    /// they resolve against the prebuilt `RouteTable`, and this serves the
+    /// control plane and the scrape path. Cheap rather than free, since
+    /// arc-swap's hybrid strategy takes a debt slot and can fall back to a
+    /// full clone once a thread exhausts them.
+    pub fn registry(&self) -> Guard<Arc<EndpointRegistry>> {
+        self.registry.load()
+    }
+
+    /// Applies a control-plane mutation, arming the next state flush only if
+    /// it changed something.
+    ///
+    /// The closure reports whether it changed anything, and a `false` costs
+    /// nothing beyond the clone. Arming unconditionally let an authenticated
+    /// caller turn a stream of no-ops, repeatedly revoking an already-revoked
+    /// endpoint, into one registry serialization and one state-store write per
+    /// 404, which is a remote write on the HTTP state backend.
+    pub fn mutate_registry(&self, mutation: impl FnOnce(&mut EndpointRegistry) -> bool) -> bool {
+        {
+            // `std::sync::Mutex`, because the guard never spans an await: the
+            // mutation is a sync closure and the swap is a store. Holding a
+            // `tokio::sync::Mutex` here only bought the ability to yield to a
+            // contender, and contention is control-plane traffic alone.
+            let _writer = self
+                .registry_writer
+                .lock()
+                .unwrap_or_else(PoisonError::into_inner);
+            let mut next = EndpointRegistry::clone(&self.registry.load());
+            if !mutation(&mut next) {
+                return false;
+            }
+            // Before the publish, not after. A reader between the two sees a
+            // registry that has not changed yet and is told a flush is owed,
+            // which is the harmless direction. The other order let it see the
+            // change and be told nothing was outstanding, which is what the
+            // per-endpoint flag used to exist to paper over.
+            self.registry_dirty.store(true, Ordering::Release);
+            self.pending_changes.fetch_add(1, Ordering::AcqRel);
+            self.registry.store(Arc::new(next));
+        }
+        // Notified after the gate is free, so the woken poll finds it open
+        // rather than bouncing off `try_lock` and relying on the re-arm there.
+        self.state_flush.notify_one();
+        true
+    }
+
+    /// Whether a mutation is still waiting to be handed to the runtime.
+    pub fn has_pending_state(&self) -> bool {
+        self.registry_dirty.load(Ordering::Acquire)
+    }
+
+    /// Names the auth posture of every path this instance serves.
+    ///
+    /// A misspelled `auth_bearer_token` key does not fail the config, it just
+    /// deserializes to `None`, and the named-path handler skips its whole auth
+    /// block when it is `None`. So the difference between "guarded" and "open
+    /// to the internet" is one silent typo. Saying it out loud at open is what
+    /// makes that visible without turning every env override into an error,
+    /// which is what `deny_unknown_fields` here would do.
+    pub fn log_auth_posture(&self) {
+        if let Some(topic_path) = &self.config.topic_path {
+            if self.config.auth_bearer_token.is_some() {
+                info!(
+                    "Serving POST /topics/{topic_path} with bearer auth for {CONNECTOR_NAME} connector ID: {}",
+                    self.id
+                );
+            } else {
+                warn!(
+                    "Serving POST /topics/{topic_path} with NO authentication for {CONNECTOR_NAME} connector ID: {}; set auth_bearer_token to guard it",
+                    self.id
+                );
+            }
+        }
+
+        let unguarded = self
+            .registry()
+            .serving_count_without_auth(unix_now_seconds());
+        if unguarded > 0 {
+            warn!(
+                "Serving {unguarded} secret-path endpoints with no second factor for {CONNECTOR_NAME} connector ID: {}; anyone holding the URL can post to them",
+                self.id
+            );
+        }
+    }
+
+    /// Whether the poll task still looks alive.
+    ///
+    /// An in-flight poll counts even when it has been blocked on an empty
+    /// bridge for hours, which is the normal state of a quiet gateway. The
+    /// timestamp covers the other case, where the SDK is between polls waiting
+    /// for a batch result. Neither advances once the poll task has stopped.
+    pub fn poll_is_live(&self, now_seconds: u64) -> bool {
+        self.poll_active.load(Ordering::Acquire)
+            || now_seconds.saturating_sub(self.last_poll_at.load(Ordering::Acquire))
+                <= POLL_LIVENESS_SECONDS
+    }
+
+    pub(crate) fn enter_poll(&self) -> PollGuard<'_> {
+        self.poll_active.store(true, Ordering::Release);
+        PollGuard(self)
+    }
+
+    /// Re-arms a flush whose state was taken but never persisted.
+    ///
+    /// `take_dirty_state` clears the flag and sets the pending change count
+    /// aside before the state leaves the plugin, so a caller that later learns
+    /// the save did not land has to put both back. Without it the mutation is
+    /// never retried and nothing on the control API says so.
+    pub fn rearm_state_flush(&self) {
+        self.registry_dirty.store(true, Ordering::Release);
+        let handed = self.handed_changes.swap(0, Ordering::AcqRel);
+        self.pending_changes.fetch_add(handed, Ordering::AcqRel);
+        let attempt = self.state_flush_nacks.fetch_add(1, Ordering::AcqRel);
+        let delay = state_flush_retry_delay(attempt);
+        if delay.is_zero() {
+            self.state_flush.notify_one();
+            return;
+        }
+        // Re-posting immediately turns a latched state store into a tight
+        // loop: `poll()` produces another state-only batch, the runtime
+        // refuses it for the same reason, and the SDK stops the source after
+        // five of those without calling `close()`. Backing off keeps the
+        // mutation deliverable without spending that budget on a store that
+        // is not going to answer yet. Dropping the permit instead would leave
+        // an idle gateway, one with no traffic and no further mutations, with
+        // no wakeup at all.
+        let state_flush = Arc::clone(&self.state_flush);
+        tokio::spawn(async move {
+            tokio::time::sleep(delay).await;
+            state_flush.notify_one();
+        });
+    }
+
+    /// Clears the refused-flush backoff once the runtime accepts a batch.
+    pub fn clear_state_flush_backoff(&self) {
+        self.state_flush_nacks.store(0, Ordering::Release);
+        self.handed_changes.store(0, Ordering::Release);
+    }
+
+    /// Mutations that have not been handed to the runtime, or were handed over
+    /// and came back NACKed. What `close()` reports as lost on a stop.
+    pub fn pending_change_count(&self) -> usize {
+        self.pending_changes.load(Ordering::Acquire)
+    }
+
+    /// Hands the registry to the runtime for persistence, once per mutation.
+    ///
+    /// Only ever called for an empty batch. The runtime saves state solely on
+    /// the success branch of the Iggy send, so attaching state to a batch of
+    /// messages would let a failed send skip the save while this side had
+    /// already cleared the flag, losing a revocation tombstone with no trace.
+    /// An empty batch cannot fail *for want of a successful publish*, which is
+    /// what makes it the safe carrier.
+    /// It can still be NACKed: the runtime short-circuits the send stage when
+    /// its own state storage is latched or a pending checkpoint will not
+    /// resolve, which is why `on_nack` re-arms rather than assuming success.
+    ///
+    /// Static-only instances never arm the flag, so their polls return
+    /// `state: None` and the runtime writes no state file at all.
+    pub fn take_dirty_state(&self) -> Option<ConnectorState> {
+        // `try_lock`, never `lock().await`. `poll()` calls this holding a
+        // batch that has already left the bridge, and the SDK drops the poll
+        // future on shutdown; an await here would lose those messages
+        // uncounted. Contention comes only from a concurrent management call,
+        // and losing that race just leaves the flag armed for the next poll.
+        let Ok(_writer) = self.registry_writer.try_lock() else {
+            // Mid-mutation. If the permit that woke this poll was theirs we
+            // have just consumed it, so re-post rather than sleep on a flush
+            // that no further traffic would ever carry. Gated on the flag so a
+            // poll that raced a mutation carrying nothing does not wake itself.
+            if self.registry_dirty.load(Ordering::Acquire) {
+                self.state_flush.notify_one();
+            }
+            return None;
+        };
+        if !self.registry_dirty.swap(false, Ordering::AcqRel) {
+            return None;
+        }
+        let snapshot = self.registry.load_full();
+        let Some(state) = snapshot.to_connector_state(self.id) else {
+            // Serialization logged the cause. The flag goes back so the next
+            // poll retries, but deliberately without re-posting the permit:
+            // doing that makes the next poll immediate, and since nothing
+            // about the registry has changed it fails identically, re-arms,
+            // and spins the poll task through a full FFI round trip per
+            // iteration with no exit. Traffic or the next mutation carries it.
+            self.registry_dirty.store(true, Ordering::Release);
+            return None;
+        };
+        // The batch is not acknowledged yet, so the count moves aside rather
+        // than being dropped: `rearm_state_flush` puts it back on a NACK.
+        self.handed_changes.store(
+            self.pending_changes.swap(0, Ordering::AcqRel),
+            Ordering::Release,
+        );
+        Some(state)
+    }
+}
+
+/// Deliberately not `Serialize`. The runtime keeps plugin configuration as raw
+/// JSON and never serializes this struct, so nothing needs it, and without it
+/// the compiler guarantees a credential cannot be written out by some future
+/// caller. `SecretString` has no `Serialize` impl for exactly that reason.
+#[derive(Debug, Clone, Deserialize)]
+pub struct HttpSourceConfig {
+    /// Public listener shared by all instances of this plugin; every
+    /// instance must configure the identical address.
+    pub listen_addr: String,
+    /// Management + observability listener; never route it through the
+    /// public load balancer.
+    #[serde(default = "default_admin_listen_addr")]
+    pub admin_listen_addr: String,
+    #[serde(default = "default_max_body_size_bytes")]
+    pub max_body_size_bytes: usize,
+    /// Capacity of this instance's HTTP-to-poll bridge, in messages. A full
+    /// bridge answers 429.
+    #[serde(default = "default_buffer_capacity")]
+    pub buffer_capacity: usize,
+    /// Maximum messages returned by a single `poll()`.
+    #[serde(default = "default_max_batch_size")]
+    pub max_batch_size: usize,
+    /// Path segment exposed as `POST /topics/{topic_path}`. Unset disables
+    /// the named path, leaving only secret-path endpoints.
+    #[serde(default)]
+    pub topic_path: Option<String>,
+    /// Identifies this instance in forwarded message headers and on the admin
+    /// listener. Defaults to the connector ID: the runtime keeps the connector
+    /// key on its own side of the FFI, so the plugin cannot read it.
+    #[serde(default)]
+    pub instance_name: Option<String>,
+    /// Guards the named topic path; unset leaves that path unauthenticated
+    /// (for deployments fronted by an authenticating gateway).
+    #[serde(default)]
+    pub auth_bearer_token: Option<SecretString>,
+    /// Enables `/admin/endpoints`; unset disables dynamic management.
+    #[serde(default)]
+    pub management_token: Option<SecretString>,
+    #[serde(default = "default_true")]
+    pub include_http_metadata: bool,
+    /// HTTP request headers forwarded as Iggy message headers, clamped to
+    /// the 255-byte `HeaderValue` limit.
+    #[serde(default)]
+    pub forward_headers: Vec<String>,
+    /// Statically configured secret-path endpoints.
+    #[serde(default)]
+    pub endpoints: Vec<StaticEndpointConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StaticEndpointConfig {
+    pub endpoint_id: EndpointId,
+    #[serde(default)]
+    pub auth_type: EndpointAuthType,
+    #[serde(default)]
+    pub auth_secret: Option<SecretString>,
+    #[serde(default = "default_hmac_header")]
+    pub hmac_header: String,
+    #[serde(default = "default_hmac_prefix")]
+    pub hmac_prefix: String,
+    /// Unix seconds; requests arriving at or after this answer 404.
+    #[serde(default)]
+    pub expires_at: Option<u64>,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EndpointAuthType {
+    #[default]
+    None,
+    Bearer,
+    HmacSha256,
+    HmacSha1,
+}
+
+impl EndpointAuthType {
+    /// The ring algorithm this auth type verifies with, if it verifies at all.
+    ///
+    /// Returning ring's type directly, rather than mirroring these two variants
+    /// into a second enum, is what keeps the two from drifting.
+    pub fn hmac_algorithm(self) -> Option<hmac::Algorithm> {
+        match self {
+            Self::HmacSha256 => Some(hmac::HMAC_SHA256),
+            Self::HmacSha1 => Some(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY),
+            Self::None | Self::Bearer => None,
+        }
+    }
+}
+
+impl HttpSourceConfig {
+    fn validate(&self) -> Result<(), Error> {
+        self.listen_addr.parse::<SocketAddr>().map_err(|error| {
+            Error::InvalidConfigValue(format!("listen_addr '{}': {error}", self.listen_addr))
+        })?;
+        self.admin_listen_addr
+            .parse::<SocketAddr>()
+            .map_err(|error| {
+                Error::InvalidConfigValue(format!(
+                    "admin_listen_addr '{}': {error}",
+                    self.admin_listen_addr
+                ))
+            })?;
+        if self.buffer_capacity == 0 || self.buffer_capacity > BUFFER_CAPACITY_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "buffer_capacity {} must be between 1 and {BUFFER_CAPACITY_LIMIT}",
+                self.buffer_capacity
+            )));
+        }
+        if self.max_batch_size == 0 || self.max_batch_size > MAX_BATCH_SIZE_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_batch_size {} must be between 1 and {MAX_BATCH_SIZE_LIMIT}",
+                self.max_batch_size
+            )));
+        }
+        if self.max_body_size_bytes == 0 || self.max_body_size_bytes > MAX_BODY_SIZE_BYTES_LIMIT {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} must be between 1 and {MAX_BODY_SIZE_BYTES_LIMIT}",
+                self.max_body_size_bytes
+            )));
+        }
+        if let Some(instance_name) = &self.instance_name {
+            if HeaderKey::try_from(instance_name.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' must be a valid Iggy header key: non-empty and at most 255 bytes"
+                )));
+            }
+            if instance_name == crate::metrics::UNROUTED {
+                // Requests to a genuinely unknown path are metered under this
+                // name, and that series is what an operator watches for
+                // endpoint-id scanning. An instance claiming it would merge
+                // real traffic into the signal.
+                return Err(Error::InvalidConfigValue(format!(
+                    "instance_name '{instance_name}' is reserved for requests that match no route"
+                )));
+            }
+        }
+        for header in &self.forward_headers {
+            let Ok(name) = HeaderName::from_str(header) else {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid HTTP header name"
+                )));
+            };
+            // Forwarding a reusable credential would copy it onto every
+            // message and into the log Iggy persists. A per-body signature
+            // header is fine; these are not.
+            if name == header::AUTHORIZATION
+                || name == header::PROXY_AUTHORIZATION
+                || name == header::COOKIE
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' would copy a credential onto every message"
+                )));
+            }
+            // `message_headers` writes the gateway's own metadata into the
+            // same map first, so forwarding a request header under one of
+            // these keys lets the sender overwrite a value the pipeline
+            // treats as trusted.
+            if matches!(
+                name.as_str(),
+                INSTANCE_HEADER | REMOTE_ADDR_HEADER | RECEIVED_AT_HEADER
+            ) {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is reserved for the gateway's own metadata"
+                )));
+            }
+            if HeaderKey::try_from(header.as_str()).is_err() {
+                return Err(Error::InvalidConfigValue(format!(
+                    "forward_headers entry '{header}' is not a valid Iggy header key"
+                )));
+            }
+        }
+        if let Some(topic_path) = &self.topic_path
+            && (topic_path.is_empty() || topic_path.contains('/'))
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "topic_path '{topic_path}' must be a single non-empty path segment"
+            )));
+        }
+        for header in [
+            ("auth_bearer_token", &self.auth_bearer_token),
+            ("management_token", &self.management_token),
+        ] {
+            if let (field, Some(secret)) = header
+                && secret.expose_secret().is_empty()
+            {
+                return Err(Error::InvalidConfigValue(format!(
+                    "{field} must not be empty; omit it entirely to disable that guard"
+                )));
+            }
+        }
+        let mut seen: BTreeSet<&EndpointId> = BTreeSet::new();
+        for endpoint in &self.endpoints {
+            if !seen.insert(&endpoint.endpoint_id) {
+                // The registry is a map, so a second block with the same id
+                // silently last-wins, and a copy-paste whose second copy
+                // carries a weaker auth_type is the one that gets served.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} is declared more than once",
+                    endpoint.endpoint_id.log_prefix()
+                )));
+            }
+            if HeaderName::from_str(&endpoint.hmac_header).is_err() {
+                // An invalid name makes `HeaderMap::get` return `None`, so
+                // every signed request 401s forever with nothing naming why.
+                return Err(Error::InvalidConfigValue(format!(
+                    "endpoint {} declares hmac_header '{}', which is not a valid HTTP header name",
+                    endpoint.endpoint_id.log_prefix(),
+                    endpoint.hmac_header
+                )));
+            }
+            if endpoint.auth_type != EndpointAuthType::None

Review Comment:
   `validate()` and the management API admit different endpoints from the same data, and only the API copy stayed current. Here the empty-secret test is hand-inlined even though `auth.rs:52` documents `is_usable_secret` as shared "so the config path and the management API cannot disagree about it".
   
   Two admissions the API refuses and this does not:
   
   - `auth_type = "none"` carrying an `auth_secret`. `management.rs:124` answers 400; here the unused secret rides `Endpoint::from` into the route table and, after any mutation, into the state file in clear, where no code path ever reads it.
   - An `expires_at` already past. `management.rs:130` answers 400; here it is accepted silently, the endpoint 404s forever, and `open()`'s serving count is the only hint.
   
   You caught this same divergence by hand twice already, on `hmac_header` and on the helper itself. Worth fixing once rather than three times: one `admit_endpoint(auth_type, auth_secret, hmac_header, expires_at, now)` beside `is_usable_secret`, called from `validate()`, `register_endpoint` and `rotate_secret`, with the inline copies deleted.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5434305546

   Ready for another look. Everything in the review is addressed, and I put the branch through two independent review rounds afterwards, which found ten more defects. Two of those changed behaviour you already reviewed, so they are first.
   
   **`/health` now requires every instance on the listener to be polling, not any.** The gate exists because the SDK stops a poll task after five consecutive NACKs without calling `close()`, leaving the instance joined and accepting into a bridge nobody drains. `any` only delivered that for a single instance, and the shared listener is the topology the whole `SERVERS` and `RouteTable` design is for: with two instances on one address, a stopped poll task on one kept the address in rotation while its webhooks were accepted and lost. One load balancer fronts both, so it can only take them in or out together; shedding the healthy sibling costs availability a sender recovers by retrying, where the alternative loses requests already answered 200.
   
   **`submitted` is now derived rather than read off the endpoint.** `take_dirty_state` marks the whole registry submitted before the state leaves, and a NACK re-arms the flush without clearing it, so the flag claimed a revocation was durable when nothing had been written. It is now paired with whether a flush is still owed: one relaxed load, no registry write, no lock. I had previously written in the README that this could not be fixed without rewriting the registry from a sync path; that was wrong, because the flag never needed to be cleared in place.
   
   A real race also turned up in code added for your review: `PollGuard::drop` cleared the in-flight flag before writing the timestamp, and `poll_is_live` reads the two as an unsynchronised pair, so a reader landing between them saw "not polling" beside the constructor's zero and `/health` answered 503 for a healthy source. Writing the timestamp first closes it.
   
   The rest of what the rounds found, all fixed: `POST /admin/endpoints` accepted an unparsable `hmac_header` (you called this out and I had only fixed the static half; the dynamic path is the worse one, since it mints an endpoint that 401s forever and survives a restart, and restore now warns when older state carries one); `mutate_registry` armed a state write per no-op, so repeatedly revoking a tombstone drove one serialization and one remote write per 404 from an authenticated caller; `received_at_micros` stamped the epoch on a clock behind 1970; `instance_name` could claim the reserved `unrouted` metric label; `strip_bearer` rejected the `1*SP` RFC 9110 permits; `poll()` reserved `max_batch_size` on every idle call; and `StatusClass`'s redirect arm had no assertion behind its catch-all, so every 3xx could have silently metered as 5xx.
   
   Ten comment and doc claims were factually wrong and are corrected. The one worth naming is "an empty send cannot fail", which appeared in three places including on `mark_submitted`: #3940 gave the runtime a state-storage short-circuit that NACKs before the producer is called, so `on_nack`'s re-arm is load-bearing rather than defensive, and anyone trusting the old comment would have deleted it.
   
   Four things I deliberately have not changed, because they are yours to call:
   
   - The public named path buffers the request body before the bearer check, the same ordering you flagged in `management.rs`. Fixing it properly means `ServerState` carrying the body limit and restructuring the handler to authorize first, so I did not want to reshape the request path unasked.
   - `close()` has no flush hook, so a state handover lost to a shutdown race is unrecoverable. That looks inherent to the `Source` contract rather than something this connector can fix.
   - `http_source_request_duration_seconds` starts its clock after axum has run the extractors, so it cannot see body read time. Measuring accept-to-200 needs a tower layer; for now the docs say what the number actually is instead of what it was meant to be.
   - The `setup_source_producer` cleanup asymmetry you flagged as not mine, which is worse than it looked: `manager/source.rs` returns early without `iggy_source_close`, and `details.info.id` is assigned only after that fallible step, so a later stop closes a stale id and the orphaned instance keeps answering 200 into a bridge nothing drains. Say the word and I will send that runtime fix separately.
   
   144 unit tests and the six `connectors::http::http_source` integration tests pass; every new guard was mutation-checked, and two tests that could not fail were deleted rather than kept.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on PR #3798:
URL: https://github.com/apache/iggy/pull/3798#issuecomment-5442605013

   Correcting myself on the comment above, and filing what closing this actually lost.
   
   I wrote that #3855 supplied the backpressure coupling #3795 was going to provide. That is true only while the runtime answers inside the SDK's 30s batch-result timeout. Past it `handle_messages` stops waiting, NACKs, and polls again, so the bridge drains, the sender stops being told anything is wrong, and the pressure moves into the runtime's unbounded forwarding channel. The README said the plain version and I have bounded the claim in `2c18e0658`.
   
   That is also the half of #3795 that survived its premise, and closing the PR left it tracked nowhere, so it is now #3981 together with the second-order finding from the same review: a batch that times out and then sends successfully has its ack refused on a `take_pending_batch` id mismatch, so the runtime logs a delivery failure, bumps the error counter, and marks the connector errored for a batch that reached Iggy intact.
   
   Neither is `http_source`'s to fix, and neither blocks this PR. Filing them so the reasoning does not live only in a closed PR's comments.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3984299271


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let now_seconds = unix_now_seconds();
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // The same rule registration applies, asked here and only warned
+            // about. `restore` failing is a hard `open()` failure, so refusing
+            // would take a whole instance down over one stored value an
+            // operator cannot edit without the state file.
+            //
+            // Asked rather than re-derived, because the two hand-written checks
+            // that used to live here had already drifted from it: they covered
+            // the ceilings and a malformed `hmac_header`, and silently skipped
+            // an endpoint advertising auth with no usable secret. That one
+            // restores active, reads active on the admin API, and rejects every
+            // request forever, which is fail-closed and completely silent.
+            //
+            // `Existing`, so a stored `expires_at` that has merely passed is not
+            // reported as a fault: the endpoint answers 404 on its own path and
+            // that is the documented behaviour.
+            //
+            // Skipped for an endpoint whose expiry has already passed. Its
+            // secret is cleared below, so on the next restart this rule would
+            // report `MissingSecret` and blame the credential for a refusal
+            // that expiry already explains.
+            if !revoked
+                && !endpoint.is_expired(now_seconds)
+                && let Err(reason) = admit_endpoint(
+                    endpoint.auth_type,
+                    &endpoint.auth_secret,
+                    &endpoint.hmac_header,
+                    &endpoint.hmac_prefix,
+                    endpoint.expires_at,
+                    Admission::Existing,
+                )
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id}: {reason}; it is served but every request to it will be refused until it is re-registered",
+                    endpoint_id.log_prefix()
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    // The map was seeded from TOML, so Occupied means TOML
+                    // still declares this id: the tombstone is static whatever
+                    // the state file says. Taking the persisted `origin`
+                    // verbatim let a `Dynamic` tombstone be the entry that
+                    // outranks a live TOML block, and `reclaimable_tombstones`
+                    // evicts exactly the dynamic ones, so the next restart
+                    // served that endpoint and its secret again. Reclamation is
+                    // only safe because a static tombstone is never eligible.
+                    endpoint.origin = EndpointOrigin::Static;
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    // A static entry reaches this arm only when TOML no longer
+                    // declares it. Restoring an active one resurrects an
+                    // endpoint the operator decommissioned by deleting it, and
+                    // `rotate_secret` then refuses it as static and points at a
+                    // TOML entry that is gone, so there is no way back. Its
+                    // tombstone still has to survive: re-adding the id to TOML
+                    // later must not undo a revocation.
+                    if !revoked && endpoint.origin == EndpointOrigin::Static {
+                        dropped_static += 1;
+                        continue;
+                    }
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        // Same reasoning as `revoke()`: the handler answers 404 on an expired
+        // endpoint before `authorize()` runs, so its stored secret is already
+        // dead weight, and nothing compacts the registry. Keeping it wrote a
+        // credential the operator can no longer use back to disk on every later
+        // flush, indefinitely, which is exactly what `revoke()` clears the
+        // secret to avoid.
+        //
+        // The endpoint keeps its slot and stays `Active`. Reclaiming it would
+        // make endpoints disappear on a clock condition rather than an operator
+        // action.
+        //
+        // Restore only, deliberately. An endpoint that expires while the
+        // instance is running keeps its stored secret until the next restart,
+        // because clearing it then would need a clock-driven sweep mutating the
+        // registry from `poll()`. `revoke` is what clears it immediately.
+        let mut expired_secrets = 0;
+        for endpoint in endpoints.values_mut() {
+            if endpoint.is_active()
+                && endpoint.is_expired(now_seconds)
+                && endpoint.auth_secret.is_some()
+            {
+                endpoint.auth_secret = None;

Review Comment:
   You are right, and the README was the worse half of it. Reworded in `docs(connectors): correct when an expired endpoint's secret leaves disk`.
   
   The Options row no longer promises the drop, and the paragraph below now says what actually happens: restore drops the secret from the registry the instance serves from, that drop is in memory and arms no flush, so the state file keeps its copy until an unrelated registration or revocation writes the registry out, and an instance that sees neither keeps it on disk. Revoking is named as the thing that clears it from disk, and why: a revocation is itself a mutation, so it drops the secret and persists the removal in one step.
   
   I took your reasons for not arming the flag verbatim rather than trying to be clever about it, and put them in the comment over the clear as well, since that comment had the same gap: it said the secret survives to the next restart and stopped there, which leaves the next reader believing the restart is what removes it.
   
   No code change. `docs` type on purpose so the commit does not read as one.



##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)
+            && !self.instances.is_empty()
+            && self
+                .instances
+                .iter()
+                .all(|instance| instance.poll_is_live(now_seconds))
+    }
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        // Without these, a mistyped path got axum's empty-bodied 404 and a
+        // wrong method an undocumented 405, while every other response on this
+        // listener carries `{"error": ...}`. A sender parsing that field broke
+        // on exactly the two responses a misconfiguration produces.
+        //
+        // The admin listener deliberately keeps axum's bare fallback: an
+        // unconfigured management API is not mounted at all there, and
+        // answering with this crate's error shape would make "no token
+        // configured" look like a route that exists and refused.
+        .fallback(|| async { error_response(StatusCode::NOT_FOUND, "not found") })
+        .method_not_allowed_fallback(|| async {
+            error_response(StatusCode::METHOD_NOT_ALLOWED, "method not allowed")
+        })
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))
+        .with_state(state)
+}
+
+/// A request that resolved to no instance is still metered, under [`UNROUTED`],
+/// which is where a scan for live endpoint ids shows up.
+fn instance_label(instance: Option<&Arc<SharedState>>) -> &str {
+    instance.map_or(UNROUTED, |instance| instance.instance_name.as_str())
+}
+
+fn same_token(left: &Option<SecretString>, right: &Option<SecretString>) -> bool {
+    match (left, right) {
+        (None, None) => true,
+        (Some(left), Some(right)) => secrets_match(left, right),
+        _ => false,
+    }
+}
+
+/// Takes the whole `Request` rather than a `Bytes` extractor, because axum runs
+/// extractors before the handler body: with one, an unauthenticated caller who
+/// guessed the operator-chosen `topic_path` could make the process buffer
+/// `max_body_size_bytes` before receiving its 401. The credential here is a
+/// header, so the body is only read once the request has earned it. The secret
+/// paths cannot do this for HMAC, whose signature covers the body, and there
+/// the endpoint id is itself a 128-bit secret the caller must already hold.
+async fn handle_named_path(
+    State(state): State<Arc<ServerState>>,
+    Path(topic_path): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) = named_path_outcome(&state, &topic_path, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Named,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+async fn handle_secret_path(
+    State(state): State<Arc<ServerState>>,
+    Path(endpoint_id): Path<String>,
+    ConnectInfo(remote_addr): ConnectInfo<SocketAddr>,
+    request: Request,
+) -> Response {
+    let started = Instant::now();
+    let (instance, response) =
+        secret_path_outcome(&state, &endpoint_id, remote_addr, request).await;
+    state.metrics.record_request(
+        instance_label(instance.as_ref()),
+        PathKind::Secret,
+        response.status().as_u16(),
+        started.elapsed(),
+    );
+    response
+}
+
+/// The instance the request resolved to, for the caller to label metrics with.
+/// Returning the `Arc` the lookup already produced rather than a copy of its
+/// name keeps the label allocation-free on the request path; `None` is a
+/// request that resolved to no instance, counted under [`UNROUTED`].
+async fn named_path_outcome(
+    state: &ServerState,
+    topic_path: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands them over owned, so nothing is cloned to survive the
+    // body being taken.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    let instance = {
+        let routes = &state.published().routes;
+        let Some(instance) = routes.lookup_named_path(topic_path) else {
+            return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+        };
+        Arc::clone(instance)
+    };
+
+    // Before the body: the whole point of taking the request whole.
+    if let Some(expected) = &instance.config.auth_bearer_token
+        && !validate_bearer(bearer_header(&request_headers), expected)
+    {
+        return (
+            Some(instance),
+            error_response(StatusCode::UNAUTHORIZED, "unauthorized"),
+        );
+    }
+
+    // `DefaultBodyLimit` guards the extractor, which is no longer in play, so
+    // the cap is applied here instead.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,
+        Err(error) => return (Some(instance), oversized_body_response(&error)),
+    };
+    // Resolved again for the same reason the secret path does it: the answer
+    // above is stale by however long the client took to send its body, and
+    // nothing bounds that. An instance that left in the meantime still owns a
+    // bridge whose receiver lives in `HttpSource`, so `try_send` would succeed
+    // and answer 200 for a message no `poll()` will ever drain. `leave()` reads
+    // `sender.len()` for `dropped_on_close` before that message exists, so the
+    // loss would not even be counted. `ptr_eq` also covers the swap: one
+    // instance leaves and another joins claiming the same topic path, and this
+    // request was never authorized against that one.
+    let published = state.published();
+    let serving = match published.routes.lookup_named_path(topic_path) {
+        Some(serving) if Arc::ptr_eq(serving, &instance) => serving,
+        // 503, not the 404 the first lookup answers. This caller already passed
+        // bearer auth and the path it asked for does exist; what changed is
+        // which instance serves it, mid-request. A 404 tells a sender the
+        // resource is gone and conventional clients stop retrying, so a
+        // republish window silently drops traffic that would have succeeded a
+        // moment later. `management.rs` already answers 503 for this same
+        // condition. The secret path keeps its 404 deliberately: that caller is
+        // unauthenticated, and distinguishing "wrong id" from "busy" there
+        // would confirm which endpoint ids exist.
+        //
+        // "route unavailable" rather than the "instance is closing" the admin
+        // API uses, because this arm covers two conditions and only one of them
+        // is a closure: the lookup can return nothing because the path was
+        // withdrawn, or it can return a different instance that has taken the
+        // path over. Naming a closure would be wrong for the handover, and the
+        // caller's action is the same either way. It also says no more about
+        // the listener's topology than a retry needs.
+        _ => {
+            return (
+                Some(instance),
+                error_response(StatusCode::SERVICE_UNAVAILABLE, "route unavailable"),
+            );
+        }
+    };
+    let response = enqueue(serving, &request_headers, remote_addr, body, &state.metrics);
+    (Some(instance), response)
+}
+
+async fn secret_path_outcome(
+    state: &ServerState,
+    endpoint_id: &str,
+    remote_addr: SocketAddr,
+    request: Request,
+) -> (Option<Arc<SharedState>>, Response) {
+    // `into_parts` hands the headers over owned; taking them as an extractor
+    // cloned the whole map on every request.
+    let (parts, body) = request.into_parts();
+    let request_headers = parts.headers;
+    // Scoped, so the published view is not pinned across the body read below.
+    // The read is paced by the client, so holding it would keep every route
+    // table and instance set reachable for as long as a caller cares to
+    // trickle, and would decide the outcome from a view taken before it began.
+    let instance = {
+        let published = state.published();
+        match published
+            .routes
+            .lookup_secret_path(endpoint_id, unix_now_seconds())
+        {
+            RouteLookup::Active(entry) => Arc::clone(&entry.instance),
+            // Both answer as if the endpoint never existed, so a leaked URL
+            // cannot be used to confirm it was once live: a 410 for the expired
+            // case would be returned before any credential is checked and would
+            // say exactly that. The metric still names the owning instance, so
+            // only a genuinely unknown path is `unrouted`.
+            RouteLookup::Revoked(entry) | RouteLookup::Expired(entry) => {
+                return (
+                    Some(Arc::clone(&entry.instance)),
+                    error_response(StatusCode::NOT_FOUND, "not found"),
+                );
+            }
+            RouteLookup::Unknown => {
+                return (None, error_response(StatusCode::NOT_FOUND, "not found"));
+            }
+        }
+    };
+    // Only now, once the id resolved to something that is actually serving.
+    // An unknown or revoked id used to cost a full body read before its 404,
+    // which is free amplification on the public listener. HMAC still needs the
+    // body, so the read cannot move any earlier than this.
+    let body = match axum::body::to_bytes(body, state.max_body_size_bytes).await {
+        Ok(body) => body,

Review Comment:
   Correct, and the earlier fix was placed too late. Fixed in `fix(connectors): check the bridge before the body is read, not after`.
   
   Both handlers now take a relaxed `is_full()` at the first point where the instance is known, before `to_bytes`: on the named path after the bearer check, on the secret path after the id resolves to something serving. Additive, as you said. The second resolve, `authorize`, `try_send` and the post-send departure check all still decide the outcome, and `enqueue` keeps its own check for a bridge that fills during the read.
   
   One consequence I wrote into the comment rather than leave implicit: on the secret path this necessarily runs before `authorize`, because the signature covers the body, so any gate after auth has already paid for the read. That lets a caller holding a live endpoint id learn the bridge is full without proving it holds the secret. An unknown id is already 404 above and a bad signature earns a 401, so I do not think it tells such a caller anything new, but it is a real ordering change and worth saying out loud.
   
   The metric, the log line and the 429 now come from one helper so the four sites cannot drift.
   
   Two tests, both of which fail without the check. An oversized body sent to a full bridge earns both a 413 and a 429, so whichever the handler answers names the check that ran first; with the gate removed both come back 413. One per handler.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3985241908


##########
core/connectors/sources/http_source/src/server.rs:
##########
@@ -0,0 +1,2731 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! The listener every instance of this plugin shares, and the request path.
+//!
+//! One `.so` is loaded once no matter how many `[[source]]` entries reference
+//! it, so the listeners live in a process-global registry keyed by listen
+//! address rather than on any one instance. The first `open()` binds; later
+//! ones validate their config against the running server and join; the last
+//! `close()` releases the ports, which the runtime's stop-then-start restart
+//! flow depends on.
+
+use arc_swap::{ArcSwap, Guard};
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{ConnectInfo, DefaultBodyLimit, Path, Request, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, serve};
+use iggy_common::{HeaderKey, HeaderValue};
+use iggy_connector_sdk::Error;
+use rand::RngExt;
+use ring::hmac;
+use secrecy::SecretString;
+use serde::Serialize;
+use std::collections::{BTreeMap, HashMap};
+use std::net::SocketAddr;
+use std::str::FromStr;
+use std::sync::{Arc, LazyLock};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, Notify, watch};
+use tokio::task::JoinHandle;
+use tracing::{debug, error, info, warn};
+
+use crate::auth::{is_usable_secret, secrets_match, validate_bearer, validate_hmac};
+use crate::metrics::{Metrics, PathKind, UNROUTED};
+use crate::routes::{Endpoint, EndpointOrigin, RouteLookup, RouteTable};
+use crate::types::{QueuedMessage, clamp_header_value, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, HttpSourceConfig, SharedState, management};
+
+/// Iggy header carrying the instance an accepted request was routed to.
+pub const INSTANCE_HEADER: &str = "iggy_source_instance";
+/// Iggy header carrying the peer address the request arrived from.
+pub const REMOTE_ADDR_HEADER: &str = "iggy_http_remote_addr";
+/// Iggy header carrying accept time, in microseconds since the Unix epoch.
+pub const RECEIVED_AT_HEADER: &str = "iggy_http_received_at";
+
+/// How long the last `close()` waits for in-flight requests before abandoning
+/// the listener tasks. Bounded so a wedged connection cannot stall shutdown.
+const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// `Retry-After` on a 429, in seconds. Named because a test asserts it and a
+/// bare literal in two places drifts.
+const RETRY_AFTER_SECONDS: &str = "1";
+
+/// How long a `join()` waits for a draining listener to release its address.
+/// Longer than [`SHUTDOWN_TIMEOUT`], since the drain it is waiting on is
+/// itself bounded by that.
+const DRAIN_WAIT_TIMEOUT: Duration = Duration::from_secs(8);
+
+/// Registers an instance with the listener for its configured address,
+/// binding that listener if this is the first instance to ask for it.
+pub async fn join(instance: Arc<SharedState>) -> Result<(), Error> {
+    let listen_addr = instance.config.listen_addr.clone();
+    let mut servers = SERVERS.lock().await;
+
+    if let Some(server) = servers.get_mut(&listen_addr) {
+        if server.draining {
+            // A sibling is mid-shutdown. Failing here turns two concurrent
+            // restarts on one listener into one instance left stopped, so wait
+            // for the entry to go and try again. The waiter is enrolled before
+            // the guard is released, or the notify could fire into the gap and
+            // be missed.
+            let drained = Arc::clone(&server.drained);
+            let mut waiter = Box::pin(drained.notified());
+            waiter.as_mut().enable();
+            drop(servers);
+            if tokio::time::timeout(DRAIN_WAIT_TIMEOUT, waiter)
+                .await
+                .is_err()
+            {
+                return Err(Error::InitError(format!(
+                    "The {CONNECTOR_NAME} listener on {listen_addr} was still shutting down after {}s; retry the open once its port is released",
+                    DRAIN_WAIT_TIMEOUT.as_secs()
+                )));
+            }
+            return Box::pin(join(instance)).await;
+        }
+        server.ensure_compatible(&instance.config)?;
+        let mut instances = server.state.instances();
+        // Names address instances in the management API and label every
+        // metric series, so a duplicate would silently route registrations to
+        // whichever instance happens to sit first in the list. Both are scoped
+        // to this listener, which is why the check is too.
+        if instances
+            .iter()
+            .any(|joined| joined.instance_name == instance.instance_name)
+        {
+            return Err(Error::InvalidConfigValue(format!(
+                "instance_name '{}' is already used by another instance on {listen_addr}",
+                instance.instance_name
+            )));
+        }
+        instances.push(Arc::clone(&instance));
+        server.state.publish(instances)?;
+        info!(
+            "Joined {CONNECTOR_NAME} connector ID: {} to the listener on {listen_addr}",
+            instance.id
+        );
+        return Ok(());
+    }
+
+    // Build the routes before binding: a config that cannot produce a valid
+    // table must not leave a port bound behind it.
+    let state = Arc::new(ServerState::new(&instance.config));
+    state.publish(vec![Arc::clone(&instance)])?;
+    let server = SharedServer::start(&instance.config, state).await?;
+    servers.insert(listen_addr.clone(), server);
+    info!(
+        "Bound the {CONNECTOR_NAME} listener on {listen_addr} for connector ID: {}, admin listener on {}",
+        instance.id, instance.config.admin_listen_addr
+    );
+    Ok(())
+}
+
+/// Deregisters an instance's routes, and shuts the listeners down once the
+/// last instance has left.
+///
+/// `staged_dropped` is folded into the same shutdown loss metric as whatever
+/// is still queued in the bridge.
+pub async fn leave(instance: &Arc<SharedState>, staged_dropped: u64) {
+    let listen_addr = &instance.config.listen_addr;
+    let mut servers = SERVERS.lock().await;
+    let Some(server) = servers.get_mut(listen_addr) else {
+        return;
+    };
+
+    let joined = server.state.instances();
+    if !joined.iter().any(|candidate| candidate.id == instance.id) {
+        // `SourceContainer::open` keeps the source even when `open()` failed,
+        // and stop closes unconditionally, so this runs for instances that
+        // never joined. Tearing down on their behalf rebuilds the route table
+        // for nothing and logs a deregistration that never happened.
+        //
+        // Deliberately untested, because the effects are not observable. The
+        // republished route set is unchanged, and the sampled gauges are
+        // rebuilt from the live instances on every scrape. A test written
+        // against those would pass with this guard removed.
+        return;
+    }
+
+    let remaining: Vec<Arc<SharedState>> = joined
+        .into_iter()
+        .filter(|candidate| candidate.id != instance.id)
+        .collect();
+    if let Err(error) = server.state.publish(remaining) {
+        // Dropping an instance cannot introduce a collision, so this is
+        // unreachable; serve nothing rather than stale routes if it happens.
+        error!(
+            "Failed to rebuild {CONNECTOR_NAME} routes after connector ID: {} left. {error}",
+            instance.id
+        );
+        server.state.serve_nothing();
+    }
+    // Read back rather than trusting the vec we hoped to publish, so the count
+    // describes what is actually being served. It is not what keeps the
+    // listener from leaking: `publish` is all-or-nothing, so on its failure
+    // branch the departed instance is still in `instances` either way. What
+    // makes that branch unreachable is that `remaining` is a subset of a table
+    // that already built, and dropping entries cannot introduce a path
+    // collision.
+    let remaining_count = server.state.instances().len();
+    info!(
+        "Deregistered {CONNECTOR_NAME} routes for connector ID: {}, instances left on {listen_addr}: {remaining_count}",
+        instance.id
+    );
+
+    // Flagged before the count, so a handler that got past the re-resolve gate
+    // and is still assembling its message sees this after its `try_send` and
+    // answers 503 rather than 200. Counting alone could not close that window:
+    // a message landing after this read is unreachable and the sender had
+    // already been told it was queued.
+    instance.mark_departed();
+    // The SDK stops the poll task before close(), so whatever is queued here is
+    // unreachable either way.
+    let dropped = instance.sender.len() as u64 + staged_dropped;
+    if dropped > 0 {
+        warn!(
+            "Dropped {dropped} queued messages closing {CONNECTOR_NAME} connector ID: {}",
+            instance.id
+        );
+        server
+            .state
+            .metrics
+            .record_dropped_on_close(&instance.instance_name, dropped);
+    }
+
+    if remaining_count == 0 {
+        // Mark the entry draining and take the tasks, but leave the entry in
+        // place while releasing the guard. Holding it across shutdown would
+        // deadlock against an in-flight management request parked on this
+        // lock; removing it outright would let a concurrent `join()` bind a
+        // port the listener is still draining. The tombstone does neither.
+        server.draining = true;
+        let signal = server.shutdown.clone();
+        let tasks = std::mem::take(&mut server.tasks);
+        drop(servers);
+
+        SharedServer::stop(signal, tasks, listen_addr).await;
+        let removed = SERVERS.lock().await.remove(listen_addr);
+        // After the removal, so a woken `join()` re-reads a map that no longer
+        // holds the drained entry and binds fresh.
+        if let Some(removed) = removed {
+            removed.drained.notify_waiters();
+        }
+    }
+}
+
+/// Every listener this process has bound, keyed by public listen address.
+///
+/// An async mutex because the guard is held across the bind and across the
+/// graceful shutdown await. Both are open/close operations, never requests.
+static SERVERS: LazyLock<Mutex<HashMap<String, SharedServer>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+struct SharedServer {
+    state: Arc<ServerState>,
+    shutdown: watch::Sender<()>,
+    tasks: Vec<JoinHandle<()>>,
+    /// Set while the listener is draining. The entry stays in the registry so
+    /// a concurrent `join()` cannot bind a port that is still held, but it can
+    /// no longer be joined.
+    draining: bool,
+    /// Fired once the drained entry has been removed from the registry, so a
+    /// `join()` that arrived mid-drain can retry instead of failing.
+    drained: Arc<Notify>,
+}
+
+/// The instance set and the routes derived from it, published as one value so
+/// no reader can see them disagree.
+#[derive(Debug, Default)]
+pub(crate) struct Published {
+    pub(crate) instances: Vec<Arc<SharedState>>,
+    pub(crate) routes: RouteTable,
+}
+
+impl Published {
+    /// Whether this listener should be taking traffic: an instance exists, a
+    /// route can reach it, and every instance is still polling.
+    ///
+    /// Every instance, not any. One load balancer fronts the whole listener, so
+    /// it can only take all of them in or out together. If one instance's poll
+    /// task has stopped while a sibling's is alive, `any` keeps the address in
+    /// rotation and the dead one's webhooks are accepted into a bridge nobody
+    /// drains, which is the exact failure this gate exists to catch. Shedding
+    /// the healthy sibling's traffic too costs availability that senders recover
+    /// by retrying; the alternative loses data already answered 200.
+    ///
+    /// Computed here so `/health` and `/admin/health` cannot answer differently
+    /// about the same listener, which is the one moment an operator reads both.
+    pub(crate) fn is_ready(&self, now_seconds: u64) -> bool {
+        self.routes.serves_anything(now_seconds)
+            && !self.instances.is_empty()
+            && self
+                .instances
+                .iter()
+                .all(|instance| instance.poll_is_live(now_seconds))
+    }
+}
+
+/// The part of a shared server the request handlers see.
+#[derive(Debug)]
+pub(crate) struct ServerState {
+    pub(crate) listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    pub(crate) admin_listen_addr: String,
+    /// Taken from the first instance to bind, like `management_token`.
+    /// `ensure_compatible` refuses a join that disagrees, so it is unambiguous.
+    /// Held here so a handler can read the body itself, after authorizing,
+    /// rather than letting an extractor buffer it first.
+    pub(crate) max_body_size_bytes: usize,
+    /// Taken from the first instance to bind. Every instance joining the same
+    /// listener must present the same token, so this is unambiguous.
+    pub(crate) management_token: Option<SecretString>,
+    pub(crate) metrics: Metrics,
+    /// Instances and the table built from them, swapped together.
+    ///
+    /// Two `ArcSwap`s let a reader land between the stores and resolve a
+    /// request against the old table while holding the new instance set, which
+    /// on a departure means routing into a bridge nobody drains. One swap makes
+    /// that unrepresentable rather than merely narrow.
+    published: ArcSwap<Published>,
+    started_at: Instant,
+}
+
+impl ServerState {
+    pub(crate) fn new(config: &HttpSourceConfig) -> Self {
+        ServerState {
+            listen_addr: config.listen_addr.clone(),
+            admin_listen_addr: config.admin_listen_addr.clone(),
+            max_body_size_bytes: config.max_body_size_bytes,
+            management_token: config.management_token.clone(),
+            metrics: Metrics::new(),
+            published: ArcSwap::from_pointee(Published::default()),
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(crate) fn instances(&self) -> Vec<Arc<SharedState>> {
+        self.published.load().instances.clone()
+    }
+
+    /// One consistent view of both. Callers that need the instance set and the
+    /// routes to agree must read them from a single guard, not two loads.
+    pub(crate) fn published(&self) -> Guard<Arc<Published>> {
+        self.published.load()
+    }
+
+    pub(crate) fn instance(&self, instance_name: &str) -> Option<Arc<SharedState>> {
+        self.published()
+            .instances
+            .iter()
+            .find(|instance| instance.instance_name == instance_name)
+            .map(Arc::clone)
+    }
+
+    /// Serves nothing until the next successful publish. Used when a mutation
+    /// removes access but the table cannot be rebuilt: stale routes would keep
+    /// honouring a credential the operator believes is gone.
+    pub(crate) fn serve_nothing(&self) {
+        // `rcu`, not load-then-store. A `publish()` from join or leave landing
+        // between the two would be discarded, and because this keeps the
+        // instance set it would leave the listener bound and serving nothing
+        // with no record of the publish that went missing.
+        let dropped = self.published.rcu(|current| {
+            // Instances are kept: they are still joined and still own bridges,
+            // and it is only the routing that is being withdrawn.
+            Arc::new(Published {
+                instances: current.instances.clone(),
+                routes: RouteTable::default(),
+            })
+        });
+        error!(
+            "Serving no {CONNECTOR_NAME} routes on {}: dropped {} secret paths and {} named paths across {} instances until the next successful publish",
+            self.listen_addr,
+            dropped.routes.secret_path_count(),
+            dropped.routes.named_path_count(),
+            dropped.instances.len()
+        );
+    }
+
+    /// Swaps in a new instance set and the routes it projects to, or leaves
+    /// both untouched if the instances collide on a path.
+    fn publish(&self, instances: Vec<Arc<SharedState>>) -> Result<(), Error> {
+        let routes = RouteTable::build(&instances)
+            .map_err(|conflict| Error::InvalidConfigValue(conflict.to_string()))?;
+        self.published
+            .store(Arc::new(Published { instances, routes }));
+        Ok(())
+    }
+}
+
+/// Reprojects a listener's route table after a management mutation.
+///
+/// Takes `SERVERS` - the listener map, not the per-instance registry gate,
+/// which the caller has already released. A mutation and a join can therefore
+/// still interleave; that is safe because the rebuild reprojects from whatever
+/// instance set is current rather than patching the previous table.
+///
+/// Blocking on the registry here is safe because `leave()` releases it before
+/// awaiting graceful shutdown; holding it across that await would deadlock,
+/// since shutdown waits for the very request that is parked here.
+pub(crate) async fn refresh_routes(listen_addr: &str) -> Result<(), Error> {
+    let servers = SERVERS.lock().await;
+    let Some(server) = servers.get(listen_addr) else {
+        return Err(Error::InitError(format!(
+            "No {CONNECTOR_NAME} listener is bound to {listen_addr}"
+        )));
+    };
+    server.state.publish(server.state.instances())
+}
+
+impl SharedServer {
+    async fn start(config: &HttpSourceConfig, state: Arc<ServerState>) -> Result<Self, Error> {
+        let public = bind("listen_addr", &config.listen_addr).await?;
+        let admin = bind("admin_listen_addr", &config.admin_listen_addr).await?;
+        let (shutdown, _) = watch::channel(());
+
+        // The one place this plugin owns background tasks. The runtime cannot
+        // drive an HTTP listener for us, so the last close() shuts them down
+        // explicitly rather than leaving them to outlive the connector.
+        let tasks = vec![
+            tokio::spawn(run(
+                public,
+                public_router(Arc::clone(&state)),
+                shutdown.subscribe(),
+                "public",
+            )),
+            tokio::spawn(run(
+                admin,
+                admin_router(state.clone(), config.max_body_size_bytes),
+                shutdown.subscribe(),
+                "admin",
+            )),
+        ];
+
+        Ok(SharedServer {
+            state,
+            shutdown,
+            tasks,
+            draining: false,
+            drained: Arc::new(Notify::new()),
+        })
+    }
+
+    /// Refuses a join whose settings disagree with the running listener.
+    ///
+    /// Fails closed on purpose: first-instance-wins would leave an operator
+    /// with a body limit or admin address their TOML says they do not have.
+    fn ensure_compatible(&self, config: &HttpSourceConfig) -> Result<(), Error> {
+        if self.state.admin_listen_addr != config.admin_listen_addr {
+            return Err(Error::InvalidConfigValue(format!(
+                "admin_listen_addr '{}' does not match '{}' on the listener already bound to {}",
+                config.admin_listen_addr, self.state.admin_listen_addr, config.listen_addr
+            )));
+        }
+        if self.state.max_body_size_bytes != config.max_body_size_bytes {
+            return Err(Error::InvalidConfigValue(format!(
+                "max_body_size_bytes {} does not match {} on the listener already bound to {}",
+                config.max_body_size_bytes, self.state.max_body_size_bytes, config.listen_addr
+            )));
+        }
+        // The management API guards one shared listener, so instances cannot
+        // hold different opinions about who may call it.
+        if !same_token(&self.state.management_token, &config.management_token) {
+            return Err(Error::InvalidConfigValue(format!(
+                "management_token does not match the one on the listener already bound to {}",
+                config.listen_addr
+            )));
+        }
+        Ok(())
+    }
+
+    async fn stop(signal: watch::Sender<()>, mut tasks: Vec<JoinHandle<()>>, listen_addr: &str) {
+        let _ = signal.send(());
+
+        // One deadline over both listeners: applied per task in a loop, the
+        // real bound would be twice SHUTDOWN_TIMEOUT.
+        let graceful = tokio::time::timeout(SHUTDOWN_TIMEOUT, async {
+            for task in &mut tasks {
+                if let Err(error) = task.await {
+                    warn!("A {CONNECTOR_NAME} listener task on {listen_addr} failed. {error}");
+                }
+            }
+        })
+        .await;
+
+        if graceful.is_err() {
+            warn!(
+                "A {CONNECTOR_NAME} listener on {listen_addr} did not stop within {SHUTDOWN_TIMEOUT:?}, aborting"
+            );
+            // `abort()` only schedules cancellation. Awaiting the handle is
+            // what guarantees the future - and the TcpListener inside it - has
+            // actually been dropped, so the runtime's stop-then-start restart
+            // cannot race the bind and fail with EADDRINUSE.
+            for task in &mut tasks {
+                // Skip the ones the graceful loop already drove to completion:
+                // awaiting a finished `JoinHandle` a second time panics, and
+                // this runs inside the FFI close of a dlopened plugin.
+                if task.is_finished() {
+                    continue;
+                }
+                task.abort();
+                match task.await {
+                    Err(error) if error.is_cancelled() => {
+                        warn!("Aborted a wedged {CONNECTOR_NAME} listener task on {listen_addr}")
+                    }
+                    Err(error) => {
+                        warn!("A {CONNECTOR_NAME} listener task on {listen_addr} panicked. {error}")
+                    }
+                    Ok(()) => {}
+                }
+            }
+        }
+        info!("Released the {CONNECTOR_NAME} listener on {listen_addr}");
+    }
+}
+
+/// Binds one listener, naming the config field it came from.
+///
+/// Both the public and admin listeners come through here, so a message that
+/// always said `listen_addr` sent an operator to the wrong line of TOML when
+/// it was the admin port that collided.
+async fn bind(field: &str, address: &str) -> Result<TcpListener, Error> {
+    TcpListener::bind(address).await.map_err(|error| {
+        // Instances are grouped by the `listen_addr` string, so two spellings
+        // of the same socket, `0.0.0.0:9090` and `127.0.0.1:9090`, are two
+        // groups and the second one tries to bind a port the first already
+        // holds. The operator sees a bind failure for a field they believe is
+        // shared, so name that possibility rather than only the OS error.
+        let hint = if error.kind() == std::io::ErrorKind::AddrInUse {
+            format!(
+                ". If another {CONNECTOR_NAME} instance is meant to share this listener, its {field} must match this one exactly"
+            )
+        } else {
+            String::new()
+        };
+        Error::InitError(format!(
+            "Failed to bind the {CONNECTOR_NAME} listener for {field} to {address}. {error}{hint}"
+        ))
+    })
+}
+
+async fn run(
+    listener: TcpListener,
+    router: Router,
+    mut shutdown: watch::Receiver<()>,
+    label: &str,
+) {
+    let service = router.into_make_service_with_connect_info::<SocketAddr>();
+    let result = serve(listener, service)
+        .with_graceful_shutdown(async move {
+            let _ = shutdown.changed().await;
+        })
+        .await;
+    if let Err(error) = result {
+        error!("The {CONNECTOR_NAME} {label} listener stopped. {error}");
+    }
+}
+
+/// No `DefaultBodyLimit`: both POST handlers take the request whole and pass
+/// the operator's cap to `to_bytes` themselves, which is what lets them refuse
+/// a request before reading it.
+fn public_router(state: Arc<ServerState>) -> Router {
+    Router::new()
+        .route("/topics/{topic_path}", post(handle_named_path))
+        .route("/e/{endpoint_id}", post(handle_secret_path))
+        .route("/health", get(handle_health))
+        // Without these, a mistyped path got axum's empty-bodied 404 and a
+        // wrong method an undocumented 405, while every other response on this
+        // listener carries `{"error": ...}`. A sender parsing that field broke
+        // on exactly the two responses a misconfiguration produces.
+        //
+        // The admin listener deliberately keeps axum's bare fallback: an
+        // unconfigured management API is not mounted at all there, and
+        // answering with this crate's error shape would make "no token
+        // configured" look like a route that exists and refused.
+        .fallback(|| async { error_response(StatusCode::NOT_FOUND, "not found") })
+        .method_not_allowed_fallback(|| async {
+            error_response(StatusCode::METHOD_NOT_ALLOWED, "method not allowed")
+        })
+        .with_state(state)
+}
+
+fn admin_router(state: Arc<ServerState>, max_body_size_bytes: usize) -> Router {
+    Router::new()
+        .route("/admin/health", get(handle_admin_health))
+        .route("/admin/metrics", get(handle_admin_metrics))
+        .merge(management::router(Arc::clone(&state)))
+        // Without this the admin listener silently used axum's 2 MiB default
+        // instead of the operator's cap, so the two listeners disagreed about
+        // how large a body they would read.
+        .layer(DefaultBodyLimit::max(max_body_size_bytes))

Review Comment:
   Fixed in `fix(connectors): give the admin listener its own limit and the cap real reach`.
   
   The admin limit is its own const now, and derived from the field caps rather than picked, so raising one of those caps cannot quietly reintroduce this. A registration is the largest legal body: `auth_secret` 4096, `hmac_header` 256, `hmac_prefix` 64, and an `instance` name Iggy's header key limit holds to 255.
   
   One thing I sized in that the arithmetic in your note does not cover. Those caps are on decoded bytes, since `admit_endpoint` measures `expose_secret().len()`, so the JSON in front of them can be up to six times larger wherever a value needs a `\u00XX` escape. A secret of control bytes is legal and would be about 24 KiB on the wire while still being a 4096 byte secret. Sizing at the 4.7 KiB of field data would have rebuilt the same bug for a narrower input, so the const is six times the field total plus a kilobyte for names and punctuation. The listener is private and token-guarded, so the slack costs nothing.
   
   I also took the point that this overshot the original ask. The comment now says only that axum's 2 MiB default is not a decision anyone made, rather than implying the two listeners ought to agree.
   
   The test registers at every field cap with `max_body_size_bytes` at its floor of 1 and expects 201. Putting the limit back on the webhook cap answers 413.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(connectors): add the HTTP source webhook gateway connector [iggy]

Posted by "mlevkov (via GitHub)" <gi...@apache.org>.
mlevkov commented on code in PR #3798:
URL: https://github.com/apache/iggy/pull/3798#discussion_r3985243436


##########
core/connectors/sources/http_source/src/state.rs:
##########
@@ -0,0 +1,1017 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Endpoint registry and its round trip through `ConnectorState`.
+//!
+//! The registry is per instance and authoritative: the route table is a
+//! projection of it, and it is the unit the runtime persists after a
+//! successful send. Endpoints created through the management API exist only
+//! here, so without this round trip a restart would drop them.
+//!
+//! Persisting them means writing their bearer tokens and HMAC secrets to the
+//! runtime state directory in the clear. That is the same at-rest posture as
+//! the TOML those endpoints would otherwise live in; the README requires
+//! `chmod 700` on the state path.
+
+use iggy_connector_sdk::{ConnectorState, Error};
+use secrecy::{ExposeSecret, SecretString};
+
+use crate::auth::{Admission, admit_endpoint};
+use serde::{Deserialize, Serialize, Serializer};
+use std::collections::BTreeMap;
+use std::collections::btree_map::Entry;
+use tracing::{info, warn};
+
+use crate::routes::{Endpoint, EndpointOrigin, EndpointState};
+use crate::types::{EndpointId, unix_now_seconds};
+use crate::{CONNECTOR_NAME, EndpointAuthType, StaticEndpointConfig};
+
+/// Ceiling on how many endpoints one instance's registry will hold.
+///
+/// Bounds the state file and the per-mutation registry clone against a caller
+/// who can register but never has to stop. Far above any real deployment: the
+/// README sizes this connector at hundreds of endpoints.
+pub const MAX_ENDPOINTS: usize = 10_000;
+
+/// Why a registration was accepted or refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InsertOutcome {
+    Inserted,
+    /// The generated id already exists. 128 bits of entropy makes this
+    /// unreachable in practice; refusing is what stops a collision silently
+    /// retargeting live traffic.
+    Collision,
+    /// At [`MAX_ENDPOINTS`] with nothing reclaimable left.
+    Full,
+}
+
+/// Every secret-path endpoint one instance owns, static and dynamic alike.
+///
+/// Ordered so the encoding is deterministic; an unordered map would produce
+/// different bytes for an identical registry.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct EndpointRegistry {
+    #[serde(default)]
+    endpoints: BTreeMap<EndpointId, Endpoint>,
+}
+
+impl EndpointRegistry {
+    /// Merges the TOML endpoints with whatever the runtime persisted.
+    ///
+    /// TOML wins for endpoints it declares: editing a static endpoint and
+    /// restarting the instance is the documented way to change it. The one
+    /// exception is a revocation tombstone, which always wins, so an operator
+    /// who revoked a compromised endpoint does not get it back by restarting
+    /// against a TOML file nobody remembered to edit.
+    /// Returns `Err` when state existed and could not be decoded. That case
+    /// cannot be served: every revocation tombstone lives in the state, so
+    /// continuing on the TOML alone would put an endpoint that was revoked for
+    /// being compromised straight back on the wire. Failing here surfaces as
+    /// `last_error` on the control API, which is the only way an operator
+    /// learns the tombstones are unreadable.
+    pub fn restore(
+        static_endpoints: &[StaticEndpointConfig],
+        state: Option<ConnectorState>,
+        connector_id: u32,
+    ) -> Result<Self, Error> {
+        let mut endpoints: BTreeMap<EndpointId, Endpoint> = static_endpoints
+            .iter()
+            .map(|config| (config.endpoint_id.clone(), Endpoint::from(config)))
+            .collect();
+        let static_count = endpoints.len();
+
+        let had_state = state.is_some();
+        let Some(persisted) = state
+            .and_then(|state| state.deserialize::<EndpointRegistry>(CONNECTOR_NAME, connector_id))
+        else {
+            if had_state {
+                return Err(Error::InitError(format!(
+                    "Cannot decode the persisted registry for {CONNECTOR_NAME} connector ID: {connector_id}. Refusing to serve {static_count} static endpoints without its revocation tombstones"
+                )));
+            }
+            info!(
+                "Started {CONNECTOR_NAME} connector ID: {connector_id} with no persisted registry, static endpoints: {static_count}"
+            );
+            return Ok(EndpointRegistry { endpoints });
+        };
+
+        let now_seconds = unix_now_seconds();
+        let mut restored = 0;
+        let mut tombstones = 0;
+        let mut dropped_static = 0;
+        for (endpoint_id, mut endpoint) in persisted.endpoints {
+            // The id is both the map key and a field, and both are written out.
+            // A hand-edited state file could disagree between them, which would
+            // split `owner_of`, keyed off the map, from `lookup_secret_path`,
+            // built from the field. The key wins.
+            endpoint.endpoint_id = endpoint_id.clone();
+            let revoked = !endpoint.is_active();
+            // The same rule registration applies, asked here and only warned
+            // about. `restore` failing is a hard `open()` failure, so refusing
+            // would take a whole instance down over one stored value an
+            // operator cannot edit without the state file.
+            //
+            // Asked rather than re-derived, because the two hand-written checks
+            // that used to live here had already drifted from it: they covered
+            // the ceilings and a malformed `hmac_header`, and silently skipped
+            // an endpoint advertising auth with no usable secret. That one
+            // restores active, reads active on the admin API, and rejects every
+            // request forever, which is fail-closed and completely silent.
+            //
+            // `Existing`, so a stored `expires_at` that has merely passed is not
+            // reported as a fault: the endpoint answers 404 on its own path and
+            // that is the documented behaviour.
+            //
+            // Skipped for an endpoint whose expiry has already passed. Its
+            // secret is cleared below, so on the next restart this rule would
+            // report `MissingSecret` and blame the credential for a refusal
+            // that expiry already explains.
+            if !revoked
+                && !endpoint.is_expired(now_seconds)
+                && let Err(reason) = admit_endpoint(
+                    endpoint.auth_type,
+                    &endpoint.auth_secret,
+                    &endpoint.hmac_header,
+                    &endpoint.hmac_prefix,
+                    endpoint.expires_at,
+                    Admission::Existing,
+                )
+            {
+                warn!(
+                    "Restored endpoint {} for {CONNECTOR_NAME} connector ID: {connector_id}: {reason}; it is served but every request to it will be refused until it is re-registered",
+                    endpoint_id.log_prefix()
+                );
+            }
+            match endpoints.entry(endpoint_id) {
+                Entry::Occupied(mut occupied) if revoked => {
+                    // The map was seeded from TOML, so Occupied means TOML
+                    // still declares this id: the tombstone is static whatever
+                    // the state file says. Taking the persisted `origin`
+                    // verbatim let a `Dynamic` tombstone be the entry that
+                    // outranks a live TOML block, and `reclaimable_tombstones`
+                    // evicts exactly the dynamic ones, so the next restart
+                    // served that endpoint and its secret again. Reclamation is
+                    // only safe because a static tombstone is never eligible.
+                    endpoint.origin = EndpointOrigin::Static;
+                    occupied.insert(endpoint);
+                    tombstones += 1;
+                }
+                Entry::Occupied(_) => {}
+                Entry::Vacant(vacant) => {
+                    // A static entry reaches this arm only when TOML no longer
+                    // declares it. Restoring an active one resurrects an
+                    // endpoint the operator decommissioned by deleting it, and
+                    // `rotate_secret` then refuses it as static and points at a
+                    // TOML entry that is gone, so there is no way back. Its
+                    // tombstone still has to survive: re-adding the id to TOML
+                    // later must not undo a revocation.
+                    if !revoked && endpoint.origin == EndpointOrigin::Static {
+                        dropped_static += 1;
+                        continue;
+                    }
+                    vacant.insert(endpoint);
+                    if revoked {
+                        tombstones += 1;
+                    } else {
+                        restored += 1;
+                    }
+                }
+            }
+        }
+        // Same reasoning as `revoke()`: the handler answers 404 on an expired
+        // endpoint before `authorize()` runs, so its stored secret is already
+        // dead weight, and nothing compacts the registry. Keeping it wrote a
+        // credential the operator can no longer use back to disk on every later
+        // flush, indefinitely, which is exactly what `revoke()` clears the
+        // secret to avoid.
+        //
+        // The endpoint keeps its slot and stays `Active`. Reclaiming it would
+        // make endpoints disappear on a clock condition rather than an operator
+        // action.
+        //
+        // Restore only, deliberately. An endpoint that expires while the
+        // instance is running keeps its stored secret until the next restart,
+        // because clearing it then would need a clock-driven sweep mutating the
+        // registry from `poll()`. `revoke` is what clears it immediately.
+        let mut expired_secrets = 0;
+        for endpoint in endpoints.values_mut() {
+            if endpoint.is_active()
+                && endpoint.is_expired(now_seconds)
+                && endpoint.auth_secret.is_some()
+            {
+                endpoint.auth_secret = None;
+                expired_secrets += 1;
+            }
+        }
+        // The third of the three restore-time faults that get a line of their
+        // own: an expired endpoint is otherwise silent at startup.
+        if expired_secrets > 0 {
+            warn!(
+                "Cleared the stored secret of {expired_secrets} expired endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id}; they keep their slot and answer 404 until re-registered"
+            );
+        }
+
+        // Loud on purpose: these were serving before the restart, and the only
+        // trace of them left is this line.
+        if dropped_static > 0 {
+            warn!(
+                "Dropped {dropped_static} persisted static endpoint(s) for {CONNECTOR_NAME} connector ID: {connector_id} that the TOML config no longer declares; they no longer serve"
+            );
+        }
+        info!(
+            "Restored registry for {CONNECTOR_NAME} connector ID: {connector_id}, static endpoints: {static_count}, dynamic endpoints: {restored}, revoked: {tombstones}"
+        );
+
+        Ok(EndpointRegistry { endpoints })
+    }
+
+    pub fn endpoints(&self) -> impl Iterator<Item = &Endpoint> {
+        self.endpoints.values()
+    }
+
+    pub fn endpoint(&self, endpoint_id: &str) -> Option<&Endpoint> {
+        self.endpoints.get(endpoint_id)
+    }
+
+    pub fn endpoint_mut(&mut self, endpoint_id: &str) -> Option<&mut Endpoint> {
+        self.endpoints.get_mut(endpoint_id)
+    }
+
+    /// [`Self::try_insert`] for tests that only care whether the registry
+    /// changed.
+    ///
+    /// Test-only on purpose. It collapses `Full` and `Collision` into one
+    /// `false`, so production code reaching for it would drop the distinction
+    /// between a registry at its ceiling and an id that is already taken, and
+    /// answer the caller the same way for both.
+    #[cfg(test)]
+    pub fn insert(&mut self, endpoint: Endpoint) -> bool {
+        self.try_insert(endpoint) == InsertOutcome::Inserted
+    }
+
+    /// Registers a new endpoint, reporting why it was refused.
+    ///
+    /// Nothing evicts tombstones on its own and every mutation clones the whole
+    /// registry, so without a ceiling a caller holding the management token can
+    /// grow the state file and the per-mutation cost without limit. At the
+    /// ceiling the oldest revoked *dynamic* entries are reclaimed first: such an
+    /// endpoint exists only here, so dropping it leaves its path answering 404
+    /// exactly as its tombstone did. A revoked static one is never reclaimed,
+    /// because its tombstone is what outranks a TOML entry that still declares
+    /// it.
+    ///
+    /// Either the whole thing succeeds or nothing is touched, so a refusal
+    /// cannot leave the registry partially reclaimed and arm a flush for it.
+    pub fn try_insert(&mut self, endpoint: Endpoint) -> InsertOutcome {
+        if self.endpoints.contains_key(&endpoint.endpoint_id) {
+            return InsertOutcome::Collision;
+        }
+        if self.endpoints.len() >= MAX_ENDPOINTS {
+            let wanted = self.endpoints.len() - MAX_ENDPOINTS + 1;

Review Comment:
   Fixed in `fix(connectors): give the admin listener its own limit and the cap real reach`, in the same commit as `server.rs:580`.
   
   All three parts as you specified them. `validate` rejects an `endpoints` list over the cap and names the count, `restore` warns and serves, and the 507's log line reports the length the registry actually holds rather than `MAX_ENDPOINTS`, which was telling an operator it was a size it was not.
   
   The asymmetry between the two is the part I want to be explicit about, because it looks inconsistent until you say why. A TOML list is something an operator can edit before starting, so refusing costs them nothing. A state file is not editable without losing every tombstone in it, so refusing there would take the instance down over a condition with no supported way to clear it. The comments on both sides say that, and each points at the other.
   
   Your eviction arithmetic is in the warning rather than left for the reader to work out: it names how many revoked entries the next registration will reclaim in one step, which at 15000 entries is the 5001 you calculated. Agreed there is no resurrection risk, static tombstones never being reclaimable, and the warning claims only the audit record.
   
   The README stated the cap as a per-instance property and now says how each source of an over-full registry is answered.
   
   Two tests. The `validate` one fails without the bound. The `restore` one does not fail without it, and I would rather say so than let it look like proof: nothing about restore's behaviour changed, so it pins the decision to warn instead of refuse, which is the part a future change is most likely to get wrong.
   
   The 507 log line has no test. This crate has no log capture, and I did not think one message was worth adding a dev-dependency for.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org