Summary
The FFI boundary structs (FfiResponse, RequestPayload) use inconsistent field naming conventions. Some fields are unprefixed, others use req_*/res_* prefixes, and the read/write semantics of handle IDs are not obvious from names alone. For v1, adapters should be able to read the field name and know what it is without consulting the spec.
Evidence
crates/iroh-http-core/src/lib.rs — RequestPayload uses req_* for request fields but body handle fields mix conventions. FfiResponse fields are unprefixed. There is no consistent rule for when a handle ID refers to a reader vs. a writer.
The lack of a naming contract means:
- Each adapter (node, deno, tauri) has independently developed its own mapping logic.
- A new adapter author must read all three existing adapters to infer conventions.
- Handle IDs for readers vs. writers look identical in the payload JSON.
Impact
- Medium: does not break existing adapters, but makes it harder to write new ones correctly and adds cognitive overhead when auditing cross-adapter parity.
Remediation
Agree on and document a naming convention before v1, then apply it uniformly:
Suggested convention:
- All handle IDs that are readers end in
_reader (e.g. body_reader, req_body_reader).
- All handle IDs that are writers end in
_writer.
- Response/request disambiguation by struct name, not prefix —
RequestPayload fields need no req_ prefix since the struct already carries that meaning.
- Document the convention in
docs/guidelines/ so future fields follow it automatically.
Acceptance criteria
- A naming convention for FFI payload fields is documented (in
docs/guidelines/rust.md or a new docs/guidelines/ffi.md).
- All FFI structs in
lib.rs follow the convention.
- All three adapters (node, deno, tauri) updated to use the renamed fields.
- The specification updated to reflect final field names.
- No functional change — serialised field names in JSON change only if the rename changes them, and adapters are updated atomically.
Summary
The FFI boundary structs (
FfiResponse,RequestPayload) use inconsistent field naming conventions. Some fields are unprefixed, others usereq_*/res_*prefixes, and the read/write semantics of handle IDs are not obvious from names alone. For v1, adapters should be able to read the field name and know what it is without consulting the spec.Evidence
crates/iroh-http-core/src/lib.rs—RequestPayloadusesreq_*for request fields but body handle fields mix conventions.FfiResponsefields are unprefixed. There is no consistent rule for when a handle ID refers to a reader vs. a writer.The lack of a naming contract means:
Impact
Remediation
Agree on and document a naming convention before v1, then apply it uniformly:
Suggested convention:
_reader(e.g.body_reader,req_body_reader)._writer.RequestPayloadfields need noreq_prefix since the struct already carries that meaning.docs/guidelines/so future fields follow it automatically.Acceptance criteria
docs/guidelines/rust.mdor a newdocs/guidelines/ffi.md).lib.rsfollow the convention.