Skip to content

refactor(core): adopt unified runtime architecture from ADR-014 #159

Description

@momics

Summary

Adopt the unified runtime architecture defined in ADR-014 (drafted in #C, finalised in the epic discussion #A). Restructure iroh-http-core so that the FFI dispatch and Iroh transport adapter are the only places carrying custom code, and the rest is composed from standard tower / tower-http / hyper / hyper-util building blocks.

Scope is intentionally vague right now. It will be defined by the assessment in #C and the discussion in #A. Once ADR-014 is merged, this issue gets rewritten with concrete tracer-bullet slices.

Evidence

See parent epic #A and assessment #C.

Likely (but not yet confirmed) shape

Based on initial discussion, the rework will probably involve some subset of:

  • A single Body newtype around UnsyncBoxBody<Bytes, BoxError> so all middleware composes without HRTB headaches.
  • An axum-style Service<Request<Body>, Response = Response<Body>, Error = Infallible> contract at the hyper boundary, with errors converted to responses inside the service.
  • The standard tower-http stack (CompressionLayer, RequestDecompressionLayer, TimeoutLayer, ConcurrencyLimitLayer, LoadShedLayer, AddExtensionLayer) composed once, type-erased via BoxCloneSyncService, shared across connections.
  • An extracted FFI dispatch service that handles the JS-bridge concerns separately from the tower-service concerns.
  • Removal of bespoke pieces (TowerErrorHandler, possibly parts of the per-connection task spawning) where standard equivalents exist.
  • Closure of feat(core): add inbound request body decompression on serve path #153 (request decompression) as a one-line addition that validates the new architecture works.

The actual list will be confirmed against the assessment in #C.

Impact

  • Future middleware additions become small, idiomatic, and reviewable.
  • Onboarding cost drops for contributors familiar with axum / tower / hyper.
  • We stop paying the type-system tax on every middleware change.
  • The custom-code surface in core/ shrinks to genuinely necessary pieces, each justified by an ADR-013 comment.

Remediation

Will be defined as a checklist of tracer-bullet vertical slices, each with its own PR and green CI, after #C lands. Likely shape:

  • Slice 1: introduce unified Body newtype (no behaviour change).
  • Slice 2: convert the inner service to Error = Infallible, move error→response inside.
  • Slice 3: replace bespoke per-connection wiring with the standard tower-http stack.
  • Slice 4: extract FFI dispatch service from RequestService.
  • Slice 5: add RequestDecompressionLayer (closes feat(core): add inbound request body decompression on serve path #153).
  • Slice 6: remove TowerErrorHandler and any other now-redundant code.

Acceptance criteria

  • All slices merged on main with green CI.
  • feat(core): add inbound request body decompression on serve path #153 closed.
  • docs/architecture.md updated to reflect the new runtime.
  • No new bespoke tower::Service / body-type / error-handling code in core/ without ADR-013 justification.
  • Equivalent or better benchmark numbers vs. pre-rework (no perf regression).

Part of #A. Blocked by #B and #C.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium priorityapiAPI design / ergonomicsdxDeveloper experienceenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions