zerodds-endpoint-swift 1.0 — Spec Coverage

Source: docs/specs/zerodds-endpoint-swift-1.0.md — the ZeroDDS Swift endpoint SDK spec. The marshalling comes from crates/lang-rules, column Language::Swift; this document covers the transport.

Implementation:

  • endpoints/swift/Sources/Zerodds/Zerodds.swift — wire core (Writer/Reader), XRCE framing (xrceWriteFrame/xrceReadFrame), sync Client, async AsyncReader, Transport protocol, MemTransport.
  • endpoints/swift/Reliable.swift — reliable sender/receiver state machine + HEARTBEAT/ACKNACK wire codec + AsyncWriter (compiled as its own ZeroddsReliable module).
  • endpoints/swift/Tests/ZeroddsTests/ZeroddsTests.swift — SwiftPM XCTest (byte-golden + sync/async loopback over MemTransport).
  • crates/endpoint-e2e/tests/swift.rs — ping-pong E2E over real UDP; crates/endpoint-e2e/tests/swift_reliable.rs — reliable-stream E2E, latency comparison.

Toolchain note (applies to every section): swiftc is not available on Linux (the Linux bench host). Every test below is verified locally on macOS only (this run: macOS, swift-driver 1.148.6, Swift 6.3.3, arm64). The E2E harnesses gate on swiftc_available() and emit a loud skip when the toolchain is missing (no false-green) — not re-verified on the Linux test host.

§1 XRCE framing

Spec: §1 — 8-byte XRCE header (session, stream, seq LE, submsg id 0x07 WRITE_DATA, flags, len LE) + body, byte-identical to crates/xrce + endpoints/c.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift — xrceWriteFrame/xrceReadFrame, constants xrceSessionNoKey (0x80) and xrceStreamBestEffort (0x01).

Tests: framing is exercised live via xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong/ xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong (§4); the wire core itself (Writer/Reader, cap-4 alignment, f32/f64 via .bitPattern) via ZeroddsTests.testByteIdentity (endpoints/swift/Tests/ZeroddsTests/ZeroddsTests.swift, swift test) against testdata/golden_le.bin/golden_be.bin — LE and BE byte-identical.

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, swift test: 39 tests, 0 failures).

§2 Sync Client

Spec: §2 — blocking Client: write frames + delivers synchronously, poll is a single non-blocking receive.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift::Transport protocol (deliver/receive, the sole integration point); Client (init/write/poll, monotonic seq counter, default session xrceSessionNoKey/xrceStreamBestEffort); MemTransport, an NSLock-guarded in-memory FIFO.

Tests: ZeroddsTests.testSyncLoopback (swift test, 5 samples over MemTransport); live E2E xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong (§4).

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, swift test: 39 tests, 0 failures).

§3 Async AsyncReader

Spec: §3 — AsyncReader.stream() returns an AsyncStream<[UInt8]>; an internal Task polls the Transport and yields unframed sample bodies; the consumer iterates with for await, onTermination cancels the task.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift::AsyncReader (init, stream()); the send side of the async path shares Client.write (§2) — no separate AsyncWriter type outside the reliable AsyncWriter (§5).

Tests: ZeroddsTests.testAsyncLoopback (swift test, 5 samples over MemTransport, for await); live E2E xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong (§4).

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, swift test: 39 tests, 0 failures).

§4 Ping-pong E2E (live)

Spec: §5.1 — a Swift app exchanges a typed sample with the shared Rust XRCE peer over a real UDP socket: the full stack (generated types + endpoint SDK), once sync via Client, once async via AsyncReader. §6 — the SDK and the generated module are compiled separately (Zerodds object + .swiftmodule) so the shared wire-core type names (Endianness/Writer/Reader) don’t collide.

Repo: crates/endpoint-e2e/tests/swift.rs — build_swift_app compiles Zerodds.swift as its own module (-emit-module/-emit-object), then app (generated Ping/Pong types + APP_MAIN) against it; UDPTransport implements Transport over a raw, non-blocking UDP socket.

Tests: (local, macOS, this run) - xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong — full stack via Client. - xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong — full stack via AsyncReader.

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, x86_64-unknown-linux-gnu).

§5 Reliable stream — state machine, wire, async writer

Spec: §4 (references reliable-endpoint v1.0 §3/§4) — XRCE reliable stream (stream_id 0x80, §8.4.10/§8.4.11), mirroring the reference crates/xrce/src/reliable.rs: ReliableSender.submit/pendingHeartbeat/ recvAckNack/getInFlight/inFlightSeqs; ReliableReceiver.recvData/ drainInOrder/pendingAckNack/reset. Window 16, receiver buffer 64, heartbeat 500 ms, payload ≤ 65535, RFC-1982 16-bit sequence numbers. Alongside it, the async-decoupled AsyncWriter: the producer enqueues wait-free (NSLock-guarded ring buffer, backpressure via a false return), a dedicated drain Thread holds the ReliableSender state and does all the I/O (send, heartbeat, ACKNACK-driven retransmit) — the producer never enters the kernel.

Repo: endpoints/swift/Reliable.swift — writeDataFrame/parseWriteData, heartbeatFrame/parseHeartbeat, acknackFrame/parseAckNack; ReliableSender, ReliableReceiver; AsyncWriter (ring buffer queue, NSLock, init(sendFn:recvFn:)/start/ write/close, DispatchSemaphore for shutdown rendezvous); endpoints/swift/example_reliable.swift (runnable in-process demo, no socket); endpoints/swift/reliable_tests.swift (standalone unit runner, mirroring crates/xrce/src/reliable.rs’s #[cfg(test)], not XCTest — plain swiftc/swift, prints UNIT OK).

Tests: (local, macOS, this run) - endpoints/swift/reliable_tests.swift in the swift column of tools/endpoints-gate (job integration-bindings-swift) compiles reliable_tests.swift against the ZeroddsReliable module and runs it — 16 run() test scenarios: monotonic seq (endpointswift_5_submit_assigns_monotonic_seqnrs), payload-too-large (endpointswift_5_submit_rejects_payload_too_large), window-full (endpointswift_5_submit_rejects_when_window_full), heartbeat first/silence/none (endpointswift_5_pending_heartbeat_fires_first_time/ endpointswift_5_pending_heartbeat_silenced_until_period_elapsed/ endpointswift_5_pending_heartbeat_none_when_window_empty), ACKNACK partial/full clear (endpointswift_5_recv_acknack_clears_acked_seqnrs/ endpointswift_5_recv_acknack_full_clear_when_no_bits_set), receiver in-order/reorder/ dedup/buffer-full (endpointswift_5_recv_data_buffers_in_order/ endpointswift_5_recv_data_reorders_out_of_order/endpointswift_5_recv_data_drops_duplicates/ endpointswift_5_recv_data_rejects_when_buffer_full), pending-ACKNACK bitmap (endpointswift_5_pending_acknack_marks_missing_slots), reset (endpointswift_5_reset_clears_state_completely), byte-golden (endpointswift_5_byte_golden_heartbeat_acknack: heartbeatFrame(1,3,0x80) == 80 00 01 00 0B 01 05 00 01 00 03 00 80, acknackFrame(1,0,0x80) == 80 00 01 00 0A 01 05 00 01 00 00 00 80 — identical to the reference goldens), in-process end-to-end loss recovery (endpointswift_5_end_to_end_sender_receiver_with_loss_recovery). - reliable_5_3_swift_samples_arrive_in_order_despite_dropped_datagrams — peer drops every 3rd sample once; the app retransmits directly via ReliableSender/ACKNACK; all 12 samples delivered gap-free in order. - endpoints/swift/example_reliable.swift in the swift column of tools/endpoints-gate (job integration-bindings-swift) — example_reliable.swift runs and reports sequence 0..11 verified in order.

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, x86_64-unknown-linux-gnu).

§6 Latency — ring enqueue vs. inline sendto

Spec: §5.3 — the producer path of AsyncWriter (write → NSLock ring-buffer push) must be measurably below the inline sendto syscall — the evidence that async write removes syscall latency from the producer path, not that it waits for ACKNACK.

Repo: endpoints/swift/Reliable.swift::AsyncWriter; bench harness in crates/endpoint-e2e/tests/swift_reliable.rs::SWIFT_RELIABLE_MAIN (modeBench) — 4000 iterations of inline sendto (UDP) vs. 4000 iterations of AsyncWriter.write after 100 warmup iterations, no live peer needed.

Tests: (local, macOS, this run) reliable_5_4_swift_the_producer_enqueue_costs_less_than_the_inline_send (crates/endpoint-e2e/tests/swift_reliable.rs) — two measurement runs: ring enqueue 426–560 ns vs. inline sendto 3829–3871 ns (~7–9×). The test asserts decoupled_ns < inline_ns (no fixed factor, only the inequality). The measured value fluctuates run to run (microbenchmark noise on a developer machine); the direction (decoupled beats inline) is stable.

Status: done — measured on macOS and on the Linux test host (swiftc 6.3.3, x86_64-unknown-linux-gnu).


Audit status

6 done / 0 partial / 0 open / 0 blocked / 0 n/a (informative).

Test run: in CI, crate tier and pillar jobs; the cited tests with the latest result of each job in the pipelines 8501 to 9053 of main (python3 ci/coverage_results.py --document zerodds-endpoint-swift-1.0.md):

  • python3 ci/run_integration.py integration-bindings-swift (job integration-bindings-swift) — 20 tests green.

20 cited tests green, 0 not green.

zerodds-endpoint-swift 1.0 — Spec-Coverage

Quelle: docs/specs/zerodds-endpoint-swift-1.0.md — ZeroDDS Swift Endpoint-SDK-Spec. Das Marshalling kommt aus crates/lang-rules, Spalte Language::Swift; hier steht der Transport.

Implementation:

  • endpoints/swift/Sources/Zerodds/Zerodds.swift — Wire-Core (Writer/Reader), XRCE-Framing (xrceWriteFrame/xrceReadFrame), sync Client, async AsyncReader, Transport-Protokoll, MemTransport.
  • endpoints/swift/Reliable.swift — reliable Sender/Receiver-State-Machine + HEARTBEAT/ACKNACK-Wire-Codec + AsyncWriter (als eigenes ZeroddsReliable-Modul kompiliert).
  • endpoints/swift/Tests/ZeroddsTests/ZeroddsTests.swift — SwiftPM-XCTest (Byte-Golden + sync/async Loopback über MemTransport).
  • crates/endpoint-e2e/tests/swift.rs — Ping-Pong-E2E über echtes UDP; crates/endpoint-e2e/tests/swift_reliable.rs — reliable-Stream-E2E, Latenz-Vergleich.

Toolchain-Hinweis (gilt für alle Abschnitte): swiftc steht auf Linux (Linux-Bench-Host) nicht zur Verfügung. Alle Tests unten sind ausschließlich lokal auf macOS verifiziert (dieser Durchlauf: macOS, swift-driver 1.148.6, Swift 6.3.3, arm64). Die E2E-Harnesse gaten auf swiftc_available() und melden bei fehlender Toolchain einen lauten Skip (kein false-green) — nicht auf dem Linux-Testhost re-verifiziert.

§1 XRCE-Framing

Spec: §1 — 8-Byte-XRCE-Header (session, stream, seq LE, submsg id 0x07 WRITE_DATA, flags, len LE) + Body, byte-identisch zu crates/xrce + endpoints/c.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift — xrceWriteFrame/xrceReadFrame, Konstanten xrceSessionNoKey (0x80) und xrceStreamBestEffort (0x01).

Tests: Framing wird über xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong/xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong (§4) live geübt; der Wire-Core selbst (Writer/Reader, cap-4-Alignment, f32/f64 via .bitPattern) über ZeroddsTests.testByteIdentity (endpoints/swift/Tests/ZeroddsTests/ZeroddsTests.swift, swift test) gegen testdata/golden_le.bin/golden_be.bin — LE und BE byte-identisch.

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, swift test: 39 Tests, 0 Fehlschläge).

§2 Sync Client

Spec: §2 — blockierender Client: write framet + liefert synchron, poll ist ein nicht-blockierender Einzel-Receive.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift::Transport-Protokoll (deliver/receive, der einzige Integrationspunkt); Client (init/write/poll, monotoner seq-Zähler, Default-Session xrceSessionNoKey/xrceStreamBestEffort); MemTransport als NSLock-geschützte In-Memory-FIFO.

Tests: ZeroddsTests.testSyncLoopback (swift test, 5 Samples über MemTransport); Live-E2E xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong (§4).

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, swift test: 39 Tests, 0 Fehlschläge).

§3 Async AsyncReader

Spec: §3 — AsyncReader.stream() liefert einen AsyncStream<[UInt8]>; eine interne Task pollt den Transport und yielded entrahmte Sample-Bodies; for await auf Consumer-Seite, onTermination cancelt die Task.

Repo: endpoints/swift/Sources/Zerodds/Zerodds.swift::AsyncReader (init, stream()); Sendeseitig teilt sich der async Pfad Client.write (§2) — kein separater AsyncWriter-Typ jenseits des reliable AsyncWriter (§5).

Tests: ZeroddsTests.testAsyncLoopback (swift test, 5 Samples über MemTransport, for await); Live-E2E xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong (§4).

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, swift test: 39 Tests, 0 Fehlschläge).

§4 Ping-Pong-E2E (live)

Spec: §5.1 — eine Swift-App tauscht mit dem geteilten Rust-XRCE-Peer über einen echten UDP-Socket ein typisiertes Sample aus: voller Stack (generierte Typen + Endpoint-SDK), einmal sync über Client, einmal async über AsyncReader. §6 — SDK und generiertes Modul werden getrennt kompiliert (Zerodds-Objekt + .swiftmodule), damit die geteilten Wire-Core-Typnamen (Endianness/Writer/Reader) nicht kollidieren.

Repo: crates/endpoint-e2e/tests/swift.rs — build_swift_app kompiliert Zerodds.swift als eigenes Modul (-emit-module/-emit-object), dann app (generierte Ping/Pong-Typen + APP_MAIN) dagegen; UDPTransport implementiert Transport über einen rohen, nicht-blockierenden UDP-Socket.

Tests: (lokal, macOS, dieser Durchlauf) - xrce_8_3_5_8_swift_sync_app_writes_the_ping_and_reads_the_pong — voller Stack über Client. - xrce_8_3_5_8_swift_async_app_writes_the_ping_and_reads_the_pong — voller Stack über AsyncReader.

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, x86_64-unknown-linux-gnu).

§5 Reliable Stream — State-Machine, Wire, Async-Writer

Spec: §4 (verweist auf reliable-endpoint v1.0 §3/§4) — XRCE reliable Stream (stream_id 0x80, §8.4.10/§8.4.11), spiegelt die Referenz crates/xrce/src/reliable.rs: ReliableSender.submit/pendingHeartbeat/ recvAckNack/getInFlight/inFlightSeqs; ReliableReceiver.recvData/ drainInOrder/pendingAckNack/reset. Window 16, Receiver-Buffer 64, Heartbeat 500 ms, Payload ≤ 65535, RFC-1982 16-bit Sequenznummern. Dazu der async-entkoppelte AsyncWriter: der Producer enqueued wait-free (NSLock-geschützter Ringpuffer, back-pressure via false-Rückgabe), ein dedizierter Drain-Thread hält den ReliableSender-State und macht die gesamte I/O (senden, Heartbeat, ACKNACK-getriebenes Retransmit) — der Producer geht nie in den Kernel.

Repo: endpoints/swift/Reliable.swift — writeDataFrame/parseWriteData, heartbeatFrame/parseHeartbeat, acknackFrame/parseAckNack; ReliableSender, ReliableReceiver; AsyncWriter (Ringpuffer queue, NSLock, init(sendFn:recvFn:)/start/ write/close, DispatchSemaphore fürs Shutdown-Rendezvous); endpoints/swift/example_reliable.swift (lauffähige In-Process-Demo, kein Socket); endpoints/swift/reliable_tests.swift (Standalone-Unit-Runner, mirrort crates/xrce/src/reliable.rs’s #[cfg(test)], kein XCTest — plain swiftc/swift, druckt UNIT OK).

Tests: (lokal, macOS, dieser Durchlauf) - endpoints/swift/reliable_tests.swift in der Spalte swift von tools/endpoints-gate (Job integration-bindings-swift) kompiliert reliable_tests.swift gegen das ZeroddsReliable-Modul und führt es aus — 16 run()-Testszenarien: monotone seq (endpointswift_5_submit_assigns_monotonic_seqnrs), Payload-zu-groß (endpointswift_5_submit_rejects_payload_too_large), Window-full (endpointswift_5_submit_rejects_when_window_full), Heartbeat first/silence/leer (endpointswift_5_pending_heartbeat_fires_first_time/ endpointswift_5_pending_heartbeat_silenced_until_period_elapsed/ endpointswift_5_pending_heartbeat_none_when_window_empty), ACKNACK Teil-/Voll-Clear (endpointswift_5_recv_acknack_clears_acked_seqnrs/ endpointswift_5_recv_acknack_full_clear_when_no_bits_set), Receiver In-Order/Reorder/ Dedup/Buffer-full (endpointswift_5_recv_data_buffers_in_order/ endpointswift_5_recv_data_reorders_out_of_order/endpointswift_5_recv_data_drops_duplicates/ endpointswift_5_recv_data_rejects_when_buffer_full), Pending-ACKNACK-Bitmap (endpointswift_5_pending_acknack_marks_missing_slots), Reset (endpointswift_5_reset_clears_state_completely), Byte-Golden (endpointswift_5_byte_golden_heartbeat_acknack: heartbeatFrame(1,3,0x80) == 80 00 01 00 0B 01 05 00 01 00 03 00 80, acknackFrame(1,0,0x80) == 80 00 01 00 0A 01 05 00 01 00 00 00 80 — identisch zu den Referenz-Goldens), In-Process-End-to-End-Loss-Recovery (endpointswift_5_end_to_end_sender_receiver_with_loss_recovery). - reliable_5_3_swift_samples_arrive_in_order_despite_dropped_datagrams — Peer dropt jedes 3. Sample einmalig; die App retransmittet direkt über ReliableSender/ACKNACK; alle 12 Samples lückenlos in Reihenfolge geliefert. - endpoints/swift/example_reliable.swift in der Spalte swift von tools/endpoints-gate (Job integration-bindings-swift) — example_reliable.swift läuft und meldet sequence 0..11 verified in order.

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, x86_64-unknown-linux-gnu).

§6 Latenz — Ring-Enqueue vs. inline sendto

Spec: §5.3 — der Producer-Pfad des AsyncWriter (write → NSLock-Ringpuffer-Push) muss messbar unter dem inline sendto-Syscall liegen — der Beleg, dass Async-Write die Syscall-Latenz aus dem Producer-Pfad nimmt, nicht das Warten auf ACKNACK.

Repo: endpoints/swift/Reliable.swift::AsyncWriter; Bench-Harness in crates/endpoint-e2e/tests/swift_reliable.rs::SWIFT_RELIABLE_MAIN (modeBench) — 4000 Iterationen inline sendto (UDP) vs. 4000 Iterationen AsyncWriter.write nach 100 Warmup-Iterationen, kein Live-Peer nötig.

Tests: (lokal, macOS, dieser Durchlauf) reliable_5_4_swift_the_producer_enqueue_costs_less_than_the_inline_send (crates/endpoint-e2e/tests/swift_reliable.rs) — zwei Messläufe: Ring-Enqueue 426–560 ns vs. inline sendto 3829–3871 ns (~7–9×). Assert im Test: decoupled_ns < inline_ns (kein fixer Faktor, nur die Ungleichung). Messwert schwankt lauf-zu-lauf (Mikrobenchmark-Rauschen auf einer Entwicklermaschine); die Richtung (entkoppelt schneller als inline) ist stabil.

Status: done — auf macOS und auf dem Linux-Testhost gemessen (swiftc 6.3.3, x86_64-unknown-linux-gnu).


Audit-Status

6 done / 0 partial / 0 open / 0 blocked / 0 n/a (informative).

Test-Lauf: in CI, Krate-Ebene und Säulen-Jobs; die zitierten Tests mit dem letzten Ergebnis jedes Jobs in den Pipelines 8501 bis 9053 von main (python3 ci/coverage_results.py --document zerodds-endpoint-swift-1.0.md):

  • python3 ci/run_integration.py integration-bindings-swift (Job integration-bindings-swift) — 20 Tests grün.

20 zitierte Tests grün, 0 nicht grün.