Upgrade iroh to 1.0.2 across app, iroh-gateway, and infra

[drewr]

Summary

iroh reached its first stable 1.0 release. The original target here was the v1.0.0-rc.0 candidate (May 11 2026); that and the later RCs are now obsolete — stable 1.0.0 shipped 2026-06-15 and 1.0.2 is the current latest (2026-07-06). This upgrade now targets stable 1.0.2 directly and skips all release candidates.

Three repos need work:

Repo	What changes
datum-cloud/iroh-gateway	Rust crate bump + API migration + Dockerfile MSRV bump
datum-cloud/app	Rust workspace crate bumps + API migration
datum-cloud/infra	n0computer/iroh-relay Docker image v0.97.0 → v1.0.2

Note: datum-cloud/network-services-operator has no Rust iroh code — iroh resources are managed via Kubernetes manifests in datum-cloud/infra. This issue tracks the overall upgrade; child issues are filed in each affected repo.

---

Status (2026-07-08)

• Target retargeted v1.0.0-rc.0 → stable 1.0.2 across all three repos.
• Step 0 pre-flight complete — every companion crate has a published release compatible with iroh 1.0.x (see checked boxes below). The iroh-proxy-utils / iroh-services blocking risk is cleared; the scaffolded [patch] escape hatch is no longer needed.
• iroh-services version skew resolved upstream — both app and iroh-gateway converge on 1.0.0 (no more 0.12 vs 0.13 split).
• iroh-gateway (Step 1): merged (feat: upgrade iroh to 1.0.2 iroh-gateway#13) and released v0.1.0 (2026-07-08). ghcr image publish + FluxCD image-updater rollout in flight.
• app (Step 2): merged (feat: upgrade iroh to 1.0.2 app#165) and released v0.1.0; the macOS desktop bundle notarized successfully (an earlier Apple legal-agreement 403 that had blocked bundles since 2026-07-02, unrelated to this upgrade, has since been resolved).
• infra (Step 3): merged (datum-cloud/infra#3212). Staging iroh-relay verified live on v1.0.2 (1/1 ready, restartCount 0). Edge rollout pending (Talos fleet, out of infra-MCP reach).

---

Dependency Map: Current → Target

Crate / Image	Used In	Current	Target (latest verified)
iroh	app, iroh-gateway	0.97.0	1.0.2
iroh-base	app, iroh-gateway	0.97.0	1.0.2
iroh-relay (Rust crate)	app, iroh-gateway	0.97.0	1.0.2
iroh-metrics	app, iroh-gateway	0.38.3	1.0.1
iroh-blobs	app/lib	0.99.0	0.103.0
iroh-proxy-utils	app, iroh-gateway	0.1.0	0.3.0
iroh-services	app (0.12), iroh-gateway (0.13)	0.12/0.13	1.0.0 (unified)
iroh-n0des	app/n0des-local	0.10	0.10.0
irpc-iroh	app/n0des-local	0.13	0.17.0
n0computer/iroh-relay (Docker)	infra	v0.97.0	v1.0.2 ✅ image published
Rust base image	iroh-gateway Dockerfile	rust:1.89-bookworm	rust:1.91-bookworm (MSRV bump)

MSRV for iroh 1.0.2 is Rust 1.91 (unchanged from the RC target).

---

Breaking API Changes (iroh 0.97 → 1.0.x)

Old API	New API	Files likely affected
PathWatcher	Connection::paths() (snapshot) + Connection::path_events() → PathEventStream	app/lib/src/node.rs
Connection::to_info() → ConnectionInfo	Connection::weak_handle()	app/lib/src/node.rs
Incoming::local_ip	Incoming::local_addr (returns IncomingLocalAddr)	iroh-gateway/src/endpoint.rs
Source type	removed	node.rs, endpoint.rs
CertConfig::Reloading	AcmeConfig builder	endpoint.rs, node.rs (relay config)
iroh_relay::dns::* modules	now private	iroh-gateway/src/endpoint.rs
Exhaustive enum/struct patterns	many types now #[non_exhaustive] — add _ => arms	all pattern-match sites

The breaking-change surface above was compiled against rc.0; re-verify against the stable 1.0.2 changelog before/while doing the Rust work, as APIs may have shifted further between the RC and stable.

---

Implementation Sequence

Step 0 — Pre-flight (blocking check before any edits)

Companion crates all have published releases compatible with iroh 1.0.x (verified on crates.io 2026-07-08):

• iroh-proxy-utils → 0.3.0 published

• iroh-services → 1.0.0 published (supersedes the 0.12/0.13 split)

• iroh-metrics → 1.0.1 published

• iroh-n0des (0.10.0), irpc-iroh (0.17.0) published

• relay.toml config format unchanged for iroh-relay:v1.0.x — current config uses manual TLS cert paths (cert_mode = "Manual"), and enable_relay / [tls] / [metrics] keys are all still valid.

Step 1 — datum-cloud/iroh-gateway (do first — simpler, unblocks infra rollout)

• Bump Cargo.toml: iroh/iroh-base/iroh-relay → 1.0, iroh-metrics 1.0, iroh-proxy-utils 0.3, iroh-services 1.0, n0-error 1.0
• Update Dockerfile: rust:1.89-bookworm → rust:1.91-bookworm
• Fix source breakages (compile-driven):
  • src/endpoint.rs: iroh_relay::dns::* → iroh::dns, Endpoint::empty_builder() → builder(presets::Empty)
  • gateway.rs/diagnostics.rs AnyError/context() errors resolved by the n0-error 1.0 bump (version skew, no source edit); SecretKey::generate() arg dropped, unused rand removed
• cargo build && cargo clippy && cargo test clean
• Cut a tagged release (v0.1.0, 2026-07-08) → publish-docker.yml publishes the ghcr image → FluxCD auto-rolls iroh-gateway

Tracked in: datum-cloud/iroh-gateway#11 — PR datum-cloud/iroh-gateway#13 open

Step 2 — datum-cloud/app

• Bump workspace Cargo.toml: iroh/iroh-base/iroh-relay/iroh-tickets → 1.0, iroh-metrics 1.0, iroh-proxy-utils 0.3, iroh-services 1.0, n0-error 1.0
• app/lib/Cargo.toml: iroh-blobs → 0.103.0 (also removed the obsolete pkcs8 = "=0.11.0-rc.11" pin)
• app/n0des-local/Cargo.toml: irpc/irpc-iroh → 0.17
• Fix source breakages:
  • flagged PathWatcher / conn.to_info() sites not present in current codebase
  • iroh_relay::dns → iroh::dns, Endpoint::empty_builder() → builder(presets::Empty) (node.rs)
  • iroh-services net_diagnostics/client_host features removed (now unconditional) — dropped features list
  • iroh_tickets::Ticket: to_bytes/from_bytes → encode_bytes/decode_bytes, deserialize → decode_string (state.rs)
  • SecretKey::generate() arg dropped (repo.rs, n0des-local)
• cargo check --workspace clean, cargo test --workspace 34 passed, cargo clippy clean
• Align iroh-services version between app and iroh-gateway — upstream unified on 1.0.0, so both target the same version

Tracked in: datum-cloud/app#161 — PR datum-cloud/app#165 open

Step 3 — datum-cloud/infra

• apps/network-services-operator/downstream/base/iroh-relay/deployment.yaml: v0.97.0 → v1.0.2 — merged in datum-cloud/infra#3212 (also adds the relay image to Renovate)
• Review relay.toml ConfigMap for any format changes — unchanged, manual-TLS keys valid on v1.0.x
• iroh-gateway image updates are handled automatically by FluxCD ImageUpdateAutomation once Step 1 releases

Tracked in: datum-cloud/infra#2563

Step 4 — Verification

• CI green in all three repos (gateway build/clippy/test, app 34 tests, infra kustomize)
• iroh-relay pod starts cleanly with new image — staging datum-downstream-gateway/iroh-relay on v1.0.2, 1/1 ready, restartCount 0, new ReplicaSet progressed 2026-07-08T13:45
• iroh-gateway DaemonSet rolls out on edge — verified on us-central-1-alice after cutting infra v0.67.9 (the gateway image-updater commit missed the v0.67.8 tag; edge Flux tracks semver >=0.0.0, so it needed a new tag). DS on v0.1.0, 2/2, restartCount 0; endpoint 47fed51bfd bound, live QUIC-over-relay, no errors.
• End-to-end tunnel connectivity — promoted to a proper Chainsaw integration test (tunnel stands up + flows traffic), tracked in Chainsaw integration test: tunnel stands up and flows traffic #240
• Prometheus scrape on port 9090 — iroh-relay :9090/metrics scraped directly on edge (relayserver_* series present, got_ping/sent_pong incrementing). iroh-gateway exposes :9090 (--metrics-port 9090) and is scraped by its PodMonitor; direct ad-hoc curl is correctly blocked by the namespace NetworkPolicy.

Post-upgrade finding (edge log volume): the v0.1.0 gateway emits TRACE-level QUIC packet logs. RUST_LOG=iroh=debug,iroh_proxy_utils=debug,datum_connect=debug no longer muzzles the QUIC stack because iroh 1.0 replaced quinn with its own fork crate noq/noq_proto, which the iroh= directive doesn't match. Recommend adding noq=warn,noq_proto=warn (or =info) to RUST_LOG in the downstream base/edge overlay. Tracked separately — does not block the upgrade.

---

Risks

Risk	Mitigation	Status
iroh-proxy-utils not yet updated	Local [patch] override or wait for release	✅ Cleared — 0.3.0 published
relay.toml format changed	Test staging first; keep v0.97.0 manifest on a branch as rollback	✅ Cleared — format unchanged
#[non_exhaustive] compile failures in match blocks	cargo check first; fix exhaustive patterns systematically	Open
MSRV bump breaks CI	Pin GitHub Actions Rust toolchain to ≥1.91	Open
Version skew: iroh-services 0.12 (app) vs 0.13 (iroh-gateway)	Align to same version during this upgrade	✅ Cleared — upstream unified on 1.0.0
Breaking-change list compiled against rc.0, not stable	Re-verify API surface against 1.0.2 changelog during Rust work	Open

[drewr]

Child issues filed:

• Upgrade iroh to 1.0.2 iroh-gateway#11 — Rust crate upgrades + Dockerfile MSRV bump
• Upgrade iroh to 1.0.2 app#161 — Rust workspace crate upgrades + API migration
• datum-cloud/infra#2563 — iroh-relay Docker image bump to v1.0.0-rc.0

[ecv]

Refresh 2026-07-08 — retargeted rc.0 → stable 1.0.2

The original v1.0.0-rc.0 target is obsolete. Stable 1.0.0 shipped 2026-06-15 and 1.0.2 is now the latest (2026-07-06). Brought this tracker current:

Retargeted every crate/image in the OP from v1.0.0-rc.0 to stable 1.0.2 and refreshed the dependency map with the actual latest versions (verified on crates.io / Docker Hub today):

Dep	Was (rc target)	Now
iroh / iroh-base / iroh-relay	1.0.0-rc.0 / 0.98 / 0.98	1.0.2 (unified)
iroh-metrics	verify	1.0.1
iroh-blobs	verify	0.103.0
iroh-proxy-utils	0.1.0	0.3.0
iroh-services	0.12 / 0.13	1.0.0 (skew resolved upstream)
iroh-n0des / irpc-iroh	0.10 / 0.13	0.10.0 / 0.17.0
n0computer/iroh-relay (Docker)	v1.0.0-rc.0	v1.0.2

Checked off:

• Step 0 pre-flight — all companion crates have compatible published releases, so the iroh-proxy-utils / iroh-services blocker is cleared and the [patch] escape hatch isn't needed. relay.toml format confirmed unchanged for v1.0.x (manual-TLS keys still valid).
• iroh-services version-skew risk — upstream unified on 1.0.0; app and iroh-gateway now target the same version.
• Step 3 relay.toml review — done, no changes needed.

Still open:

• Step 3 image bump — PR datum-cloud/infra#3212 open (v0.97.0 → v1.0.2), awaiting merge. That PR also adds the iroh-relay deployment to Renovate so future tags auto-PR. infra#2563 retitled to 1.0.2.
• Step 1 (iroh-gateway#11) and Step 2 (app#161) — Rust work not started; both child issues still titled for rc.0 and need their own retarget to 1.0.2.

MSRV for 1.0.2 is still Rust 1.91, so the planned Dockerfile bump stands. One caveat carried into the OP: the breaking-API-change table was compiled against rc.0 — re-verify against the 1.0.2 changelog while doing the Rust work.

[ecv]

Steps 1 & 2 implemented — PRs open (2026-07-08)

Both Rust-side upgrades are done and green against stable iroh 1.0.2:

Step	Repo	PR	Validation
1	iroh-gateway	datum-cloud/iroh-gateway#13	cargo build / clippy / test clean
2	app	datum-cloud/app#165	cargo check / clippy clean, test 34 passed
3	infra	datum-cloud/infra#3212	held as draft, gated behind 1 & 2

What the compiler actually required (vs. the original rc.0 breaking-change table)

The migration was compile-driven against 1.0.2. Notable deltas from the speculative rc.0 notes in the OP:

• PathWatcher / Connection::to_info() migrations were moot — neither symbol exists in the current app codebase, so those rows didn't apply.
• New break not in the OP: iroh-services dropped its net_diagnostics / client_host feature gates — the modules are now compiled unconditionally, so the fix was to remove the features list, not rename anything.
• New break not in the OP: iroh_tickets::Ticket was reshaped — to_bytes/from_bytes → encode_bytes/decode_bytes, and Ticket::deserialize → the trait-provided decode_string.
• Confirmed as expected: iroh_relay::dns → iroh::dns, Endpoint::empty_builder() → builder(presets::Empty), SecretKey::generate() loses its rng arg.
• n0-error version skew — bumping the pin from 0.1 to 1.0 resolved the AnyError mismatch and context() trait-bound errors with no source edits (the iroh 1.0 ecosystem, e.g. iroh-tickets, moved to n0-error 1.0.0).
• Obsolete pin dropped — app/lib no longer needs pkcs8 = "=0.11.0-rc.11"; iroh 1.0.2 resolves stable pkcs8 0.11.0, satisfying the pin's own removal TODO.

Remaining

1. Merge iroh-gateway#13 → cut a tagged release (publishes the Docker image, auto-rolls the gateway DaemonSet via FluxCD).
2. Merge app#165.
3. Un-draft & merge infra#3212 (relay image bump).
4. Step 4 verification (pod health, TLS handshake, :9090 scrape, e2e tunnel smoke test).

Caveat

app/n0des-local is excluded from the workspace but inherits workspace = true deps, so it is not standalone-buildable with cargo in its own directory (pre-existing, not a CI target). Its edits are applied for consistency but could not be compile-verified in isolation.

[ecv]

Closing — iroh 1.0.2 upgrade complete across all child repos:

• iroh-gateway datum-cloud/iroh-gateway#13 (released v0.1.0)
• app datum-cloud/app#165 (released v0.1.0)
• infra datum-cloud/infra#3212 — staging iroh-relay live on v1.0.2, 1/1 ready

No iroh version is pinned in this repo (tracker only; internal/iroh/ is a pure-Go z-base-32 helper). Remaining rollout is out of scope here: edge Talos-fleet image rollout (infra), and the e2e tunnel test tracked in #240.