zerodds-endpoint-go 1.0 — Spec Coverage
Source: docs/specs/zerodds-endpoint-go-1.0.md — the ZeroDDS Go endpoint
SDK spec. The marshalling comes from crates/lang-rules, column Language::Go; this document covers the transport.
Implementation:
endpoints/go/endpoint.go— XRCE framing (XrceWriteFrame/XrceReadFrame).endpoints/go/sync.go— syncClient.endpoints/go/async.go—Transportinterface, asyncAsyncReader/AsyncWriter.endpoints/go/reliable.go— reliable sender/receiver state machine + HEARTBEAT/ACKNACK wire codec +ReliableAsyncWriter.crates/endpoint-e2e/tests/go.rs— ping-pong E2E;crates/endpoint-e2e/tests/go_reliable.rs— reliable-stream E2E.
§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/go/endpoint.go — XrceWriteFrame/XrceReadFrame,
constants XrceSessionNoKey (0x80) and XrceStreamBestEffort (0x01).
Tests: crates/endpoint-e2e/tests/go.rs::endpoint_go_5_1_the_generated_codec_pings_without_the_xrce_frame (raw XCDR2 with no
XRCE frame — its own minimal harness); the framing itself is exercised live
via xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong and xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§2 Sync Client
Spec: §2 — blocking Client: Write frames + delivers synchronously,
Poll is a single non-blocking receive, Receive blocks up to a timeout
(polling).
Repo: endpoints/go/async.go::Transport interface (Deliver/Receive,
the sole integration point); endpoints/go/sync.go::Client
(NewClient/Write/Poll/Receive, monotonic seq counter, default
session XrceSessionNoKey/XrceStreamBestEffort).
Tests: endpoints/go/sync_test.go::Test_endpointgo_2_sync_loopback; live E2E
xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§3 Async Reader/Writer
Spec: §3 — a goroutine polls the Transport and pushes unframed sample
bodies onto a channel (push); AsyncWriter is the send-side counterpart over
the same framing.
Repo: endpoints/go/async.go::AsyncReader (NewAsyncReader, Samples
channel, background loop, Close), AsyncWriter (NewAsyncWriter,
Write).
Tests: endpoints/go/async_test.go::Test_endpointgo_3_async_loopback +
TestAsyncUDP; live E2E xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§4 Ping-pong E2E (live)
Spec: §5.1/§5.2 — a Go app exchanges a typed sample with the shared Rust XRCE peer over a real UDP socket: once as raw generated codec with no XRCE frame, once as the full stack (generated types + endpoint SDK) sync and async.
Repo: crates/endpoint-e2e/tests/go.rs — GO_RAW_MAIN (raw UDP, no XRCE
frame, uses only the generated MarshalXCDR/UnmarshalXCDRPong),
GO_ENDPOINT_MAIN (udpTransport implementing zerodds.Transport + the
zeroddsendpoint module, mode sync/async via CLI argument).
Tests: (Linux)
- endpoint_go_5_1_the_generated_codec_pings_without_the_xrce_frame — generated Ping/Pong codec directly over a raw UDP
socket, no XRCE framing.
- xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong — full stack via zerodds.Client.
- xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong — full stack via zerodds.AsyncReader/AsyncWriter.
Status: done.
§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; 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 ReliableAsyncWriter: the producer enqueues wait-free onto a
buffered channel, a dedicated drain goroutine holds the ReliableSender
state and does all the I/O (send, heartbeat, ACKNACK-driven retransmit) — the
producer never enters the kernel.
Repo: endpoints/go/reliable.go — ReliableWriteFrame/ReliableReadFrame,
HeartbeatFrame/ParseHeartbeat, AckNackFrame/ParseAckNack;
ReliableSender, ReliableReceiver; ReliableAsyncWriter (buffered channel
in, NewReliableAsyncWriter/Enqueue/Close/drain);
endpoints/go/example_reliable (runnable in-process demo, no socket);
endpoints/go/reliable_app (UDP sender app with a peer port and a count).
Tests: (Linux)
- endpoints/go/reliable_test.go in the go column of tools/endpoints-gate
(job integration-endpoints)
runs go test with -run against endpoints/go/reliable_test.go — 21 test
functions: monotonic seq (TestSubmitAssignsMonotonicSeqnrs),
payload-too-large (TestSubmitRejectsPayloadTooLarge), window-full
(TestSubmitRejectsWhenWindowFull), heartbeat first/silence/none
(TestPendingHeartbeatFiresFirstTime/...SilencedUntilPeriodElapsed/
...NoneWhenWindowEmpty), ACKNACK partial/full clear
(TestRecvAcknackClearsAckedSeqnrs/...FullClearWhenNoBitsSet), receiver
reorder/dedup/buffer-full (TestRecvDataBuffersInOrder/
...ReordersOutOfOrder/...DropsDuplicates/...RejectsWhenBufferFull),
pending-ACKNACK bitmap (TestPendingAcknackMarksMissingSlots), reset
(TestResetClearsStateCompletely), in-process end-to-end loss recovery
(TestEndToEndSenderReceiverWithLossRecovery), in-order delivery over the
reliable stream (TestConfigSubmessagesDeliveredInOrderViaReliableStream),
RFC-1982 wraparound (TestSeqLtGtRfc1982Wraparound), byte-golden
(TestByteGoldenHeartbeat/TestByteGoldenAckNack: HeartbeatFrame(1,3) ==
80 00 01 00 0B 01 05 00 01 00 03 00 80, AckNackFrame(1,0) ==
80 00 01 00 0A 01 05 00 01 00 00 00 80 — identical to the reference
goldens), frame round-trip parsing (TestFrameRoundTripParsing),
ReliableAsyncWriter loss recovery (TestReliableAsyncWriterLossRecovery).
- reliable_5_3_go_samples_arrive_in_order_despite_dropped_datagrams — peer drops every 3rd sample once; the app
the test builds from the Ping the language’s generator writes from the IDL of crates/endpoint-e2e/src/codegen.rs, and ReliableAsyncWriter retransmits on ACKNACK;
all 12 samples delivered gap-free in order, the test reads every sample by the IDL’s XCDR2 layout (assert_reliable_pings).
- reliable_5_5_go_example_recovers_its_sequence_without_gaps — example_reliable runs and reports
sequence 0..11 verified in order + RELIABLE OK.
Status: done.
§6 Latency — ring enqueue vs. inline sendto
Spec: §5.4 — the producer path of ReliableAsyncWriter (Enqueue →
channel 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/go/reliable_bench — 20000 iterations of inline
conn.Write (UDP sendto) vs. 20000 iterations of
ReliableAsyncWriter.Enqueue, no live peer needed (an arbitrary loopback
port, only local dispatch cost under measurement).
Tests: (Linux) reliable_5_4_go_the_producer_enqueue_costs_less_than_the_inline_send
(crates/endpoint-e2e/tests/go_reliable.rs) — ring enqueue 20–25 ns vs.
inline sendto 4360 ns (~175–220×).
Status: done.
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-go-1.0.md):
python3 ci/run_integration.py integration-bindings(jobintegration-bindings) — 6 tests green.python3 ci/run_integration.py integration-endpoints(jobintegration-endpoints) — 2 tests green.
8 cited tests green, 0 not green.
Open items: none.
zerodds-endpoint-go 1.0 — Spec-Coverage
Quelle: docs/specs/zerodds-endpoint-go-1.0.md — ZeroDDS Go Endpoint-SDK-Spec.
Das Marshalling kommt aus crates/lang-rules, Spalte Language::Go; hier steht der Transport.
Implementation:
endpoints/go/endpoint.go— XRCE-Framing (XrceWriteFrame/XrceReadFrame).endpoints/go/sync.go— syncClient.endpoints/go/async.go—Transport-Interface, asyncAsyncReader/AsyncWriter.endpoints/go/reliable.go— reliable Sender/Receiver-State-Machine + HEARTBEAT/ACKNACK-Wire-Codec +ReliableAsyncWriter.crates/endpoint-e2e/tests/go.rs— Ping-Pong-E2E;crates/endpoint-e2e/tests/go_reliable.rs— reliable-Stream-E2E.
§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/go/endpoint.go — XrceWriteFrame/XrceReadFrame,
Konstanten XrceSessionNoKey (0x80) und XrceStreamBestEffort (0x01).
Tests: crates/endpoint-e2e/tests/go.rs::endpoint_go_5_1_the_generated_codec_pings_without_the_xrce_frame (rohes XCDR2 ohne
XRCE-Frame — eigener Mini-Harness); Framing selbst wird über xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong
und xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong (§4) live geübt.
Status: done.
§2 Sync Client
Spec: §2 — blockierender Client: Write framet + liefert synchron,
Poll ist ein nicht-blockierender Einzel-Receive, Receive blockiert bis zu
einem Timeout (pollend).
Repo: endpoints/go/async.go::Transport-Interface (Deliver/Receive,
der einzige Integrationspunkt); endpoints/go/sync.go::Client
(NewClient/Write/Poll/Receive, monotoner seq-Zähler, Default-Session
XrceSessionNoKey/XrceStreamBestEffort).
Tests: endpoints/go/sync_test.go::Test_endpointgo_2_sync_loopback; Live-E2E
xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§3 Async Reader/Writer
Spec: §3 — Goroutine pollt den Transport und schiebt entrahmte
Sample-Bodies auf einen Channel (push); AsyncWriter als Sendeseiten-Gegenstück
über dasselbe Framing.
Repo: endpoints/go/async.go::AsyncReader (NewAsyncReader, Samples-Channel,
Hintergrund-loop, Close), AsyncWriter (NewAsyncWriter, Write).
Tests: endpoints/go/async_test.go::Test_endpointgo_3_async_loopback +
TestAsyncUDP; Live-E2E xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§4 Ping-Pong-E2E (live)
Spec: §5.1/§5.2 — eine Go-App tauscht mit dem geteilten Rust-XRCE-Peer über einen echten UDP-Socket ein typisiertes Sample aus: einmal roher generierter Codec ohne XRCE-Frame, einmal voller Stack (generierte Typen + Endpoint-SDK) sync und async.
Repo: crates/endpoint-e2e/tests/go.rs — GO_RAW_MAIN (rohes UDP, kein
XRCE-Frame, nutzt nur den generierten MarshalXCDR/UnmarshalXCDRPong),
GO_ENDPOINT_MAIN (udpTransport über zerodds.Transport +
zeroddsendpoint-Modul, Modus sync/async per CLI-Argument).
Tests: (Linux)
- endpoint_go_5_1_the_generated_codec_pings_without_the_xrce_frame — generierter Ping/Pong-Codec direkt über einen rohen
UDP-Socket, ohne XRCE-Framing.
- xrce_8_3_5_8_go_sync_app_writes_the_ping_and_reads_the_pong — voller Stack über zerodds.Client.
- xrce_8_3_5_8_go_async_app_writes_the_ping_and_reads_the_pong — voller Stack über zerodds.AsyncReader/AsyncWriter.
Status: done.
§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; ReliableReceiver.RecvData/DrainInOrder/
PendingAcknack/Reset. Window 16, Receiver-Buffer 64, Heartbeat 500 ms,
Payload ≤ 65535, RFC-1982 16-bit Sequenznummern. Dazu der async-entkoppelte
ReliableAsyncWriter: der Producer enqueued wait-free in einen gepufferten
Channel, eine dedizierte Drain-Goroutine 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/go/reliable.go — ReliableWriteFrame/ReliableReadFrame,
HeartbeatFrame/ParseHeartbeat, AckNackFrame/ParseAckNack;
ReliableSender, ReliableReceiver; ReliableAsyncWriter
(gepufferter Channel in, NewReliableAsyncWriter/Enqueue/Close/drain);
endpoints/go/example_reliable (lauffähige In-Process-Demo, kein Socket);
endpoints/go/reliable_app (UDP-Sender-App mit Peer-Port und Anzahl).
Tests: (Linux)
- endpoints/go/reliable_test.go in der Spalte go von tools/endpoints-gate
(Job integration-endpoints)
läuft go test mit -run auf endpoints/go/reliable_test.go — 21
Testfunktionen: monotone seq (TestSubmitAssignsMonotonicSeqnrs),
Payload-zu-groß (TestSubmitRejectsPayloadTooLarge), Window-full
(TestSubmitRejectsWhenWindowFull), Heartbeat first/silence/leer
(TestPendingHeartbeatFiresFirstTime/...SilencedUntilPeriodElapsed/
...NoneWhenWindowEmpty), ACKNACK Teil-/Voll-Clear
(TestRecvAcknackClearsAckedSeqnrs/...FullClearWhenNoBitsSet), Receiver
Reorder/Dedup/Buffer-full (TestRecvDataBuffersInOrder/
...ReordersOutOfOrder/...DropsDuplicates/...RejectsWhenBufferFull),
Pending-ACKNACK-Bitmap (TestPendingAcknackMarksMissingSlots), Reset
(TestResetClearsStateCompletely), In-Process-End-to-End-Loss-Recovery
(TestEndToEndSenderReceiverWithLossRecovery), In-Order-Delivery über den
reliable Stream (TestConfigSubmessagesDeliveredInOrderViaReliableStream),
RFC-1982-Wraparound (TestSeqLtGtRfc1982Wraparound), Byte-Golden
(TestByteGoldenHeartbeat/TestByteGoldenAckNack: HeartbeatFrame(1,3) ==
80 00 01 00 0B 01 05 00 01 00 03 00 80, AckNackFrame(1,0) ==
80 00 01 00 0A 01 05 00 01 00 00 00 80 — identisch zu den Referenz-Goldens),
Frame-Roundtrip-Parsing (TestFrameRoundTripParsing),
ReliableAsyncWriter-Loss-Recovery (TestReliableAsyncWriterLossRecovery).
- reliable_5_3_go_samples_arrive_in_order_despite_dropped_datagrams — Peer dropt jedes 3. Sample einmalig; die App,
die der Test aus dem Ping, den der Generator der Sprache aus der IDL von crates/endpoint-e2e/src/codegen.rs schreibt, und ReliableAsyncWriter baut, retransmittet auf
ACKNACK; alle 12 Samples lückenlos in Reihenfolge geliefert, der Test liest jedes Sample nach dem XCDR2-Layout der IDL (assert_reliable_pings).
- reliable_5_5_go_example_recovers_its_sequence_without_gaps — example_reliable läuft und meldet
sequence 0..11 verified in order + RELIABLE OK.
Status: done.
§6 Latenz — Ring-Enqueue vs. inline sendto
Spec: §5.4 — der Producer-Pfad des ReliableAsyncWriter
(Enqueue → Channel-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/go/reliable_bench — 20000 Iterationen inline conn.Write
(UDP-sendto) vs. 20000 Iterationen ReliableAsyncWriter.Enqueue, kein Live-
Peer nötig (beliebiger Loopback-Port, nur lokale Dispatch-Kosten unter
Messung).
Tests: (Linux) reliable_5_4_go_the_producer_enqueue_costs_less_than_the_inline_send
(crates/endpoint-e2e/tests/go_reliable.rs) — Ring-Enqueue 20–25 ns vs.
inline sendto 4360 ns (~175–220×).
Status: done.
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-go-1.0.md):
python3 ci/run_integration.py integration-bindings(Jobintegration-bindings) — 6 Tests grün.python3 ci/run_integration.py integration-endpoints(Jobintegration-endpoints) — 2 Tests grün.
8 zitierte Tests grün, 0 nicht grün.
Offene Punkte: keine.