zerodds-endpoint-lua 1.0 — Spec Coverage
Source: docs/specs/zerodds-endpoint-lua-1.0.md — the ZeroDDS Lua
endpoint SDK spec. The marshalling comes from crates/lang-rules, column Language::Lua; this document covers the transport.
Implementation:
endpoints/lua/zerodds.lua— XRCE framing (writeFrame/readFrame), syncClient, coroutine-basedasyncReader.endpoints/lua/reliable.lua— reliable sender/receiver state machine + HEARTBEAT/ACKNACK wire codec + cooperativeAsyncWriter.endpoints/lua/reliable_app.lua— UDP sender app (moderunagainst a peer, modebenchfor the latency test).crates/endpoint-e2e/tests/lua.rs— ping-pong E2E;crates/endpoint-e2e/tests/lua_reliable.rs— reliable-stream E2E.- Gate:
lua5.4+luasocket(thesocketmodule) on PATH; either missing → loud skip, no false green.
§1 XRCE framing
Spec: §1 — 8-byte XRCE header (session, stream, seq LE, submsg id
0x07 WRITE_DATA, flags 0x03, len LE) + body, byte-identical to
crates/xrce + endpoints/c.
Repo: endpoints/lua/zerodds.lua — M.writeFrame/M.readFrame,
constants M.SESSION_NOKEY (0x80) and M.STREAM_BEST_EFFORT (0x01).
Tests: no framing test isolated from the full stack; framing is
exercised live via xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong/xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong (§4) — every
sample round-trips through writeFrame/readFrame on the wire.
Status: done.
§2 Sync Client
Spec: §2 — polled, non-blocking Client; Write frames + delivers
synchronously, Poll is a single non-blocking receive attempt; there is no
built-in Receive(timeout) — deadline looping is the caller’s
responsibility.
Repo: endpoints/lua/zerodds.lua::Client (Client.new/Client:write/
Client:poll, session/stream defaults SESSION_NOKEY/
STREAM_BEST_EFFORT, monotonically increasing seq starting at 1);
Transport contract as a structural table {deliver, receive} (Lua has no
interface construct).
Tests: endpoints/lua/test.lua (sync loopback over memTransport,
part of the zerodds-xcdr2-lua coverage); live E2E xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong
(§4).
Status: done.
§3 Async Reader (coroutine)
Spec: §3 — asyncReader is a coroutine.wrap producer; each resume
makes exactly one transport.receive() attempt and returns the unframed
body or nil. There is no separate AsyncWriter for the best-effort path
— writing stays Client:write, identical for sync and async apps; a real
submit/drain split only exists for the reliable stream (§5), where it
carries a history cache and a periodic HEARTBEAT worth decoupling.
Repo: endpoints/lua/zerodds.lua::M.asyncReader.
Tests: endpoints/lua/test.lua (async loopback over memTransport);
live E2E xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§4 Ping-pong E2E (live)
Spec: §5.1 — a lua5.4 app exchanges a typed sample with the shared
Rust XRCE peer over a real luasocket UDP datagram: full stack (generated
zerodds-idl-lua types + endpoints/lua), both sync and async.
Repo: crates/endpoint-e2e/tests/lua.rs — LUA_MAIN (the module written
as gen.lua at test time by crates/endpoint-e2e/tests/lua.rs::gen_module, with
marshal_Ping/unmarshal_Pong as globals +
require("zerodds"), udpTransport implementing {deliver, receive}, mode
sync/async via CLI argument, 50ms socket timeout for a non-blocking
receive()).
Tests: crates/endpoint-e2e/tests/lua.rs — both cases run live against
the Rust XRCE peer over a real UDP socket:
xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong— full stack viazerodds.Client.xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong— full stack viazerodds.asyncReader.
The harness looks for the interpreter as lua5.4, lua, lua5.3 in that
order and skips loudly (SKIP lua endpoint …) when none of them or
luasocket is missing; in the job integration-bindings-gnat-beam such a
line fails the job.
Status: done.
§5 Reliable stream — state machine, wire, AsyncWriter
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: Sender:submit/pendingHeartbeat/
recvAcknack/getInFlight; Receiver:recvData/drainInOrder/
pendingAcknack/reset. Window 16, receiver buffer 64, heartbeat 500 ms,
payload ≤ 65535, RFC-1982 16-bit sequence numbers. Alongside it, the
AsyncWriter (push/drain) — cooperative, not thread-decoupled (§4
of the spec, honesty paragraph; expanded in §6 of this coverage).
Repo: endpoints/lua/reliable.lua — writeDataFrame/parseWriteData,
heartbeatFrame/parseHeartbeat, acknackFrame/parseAcknack; Sender,
Receiver; AsyncWriter (push/drain/pending/isEmpty);
endpoints/lua/example_reliable.lua (runnable in-process demo, no socket);
endpoints/lua/reliable_app.lua (UDP sender app, modes run/bench).
Tests:
endpoints/lua/reliable_test.luain theluacolumn oftools/endpoints-gate(jobintegration-endpoints) runslua5.4 reliable_test.lua <golden_dir>against the golden HEARTBEAT/ACKNACK bytes, generated by the test itself viazerodds-xrce(the same library that would surface a wire regression). Reproduced locally withlua5.5 instead oflua5.4: 48 checks, allok(ALL OK) — 44 state-machine/frame-roundtrip checks (monotonicseq, payload too large, window full, heartbeat first/silence/after period, heartbeat with an empty window, ACKNACK partial/full clear, receiver reorder/dedup/buffer-full, pending-ACKNACK bitmap, reset, in-memory end-to-end loss recovery,AsyncWriterpush/drain including the window cap) plus 4 byte-golden checks (endpointlua_5_byte_golden_heartbeat,endpointlua_5_byte_golden_acknack,endpointlua_5_golden_heartbeat_parse,endpointlua_5_golden_acknack_parse) — HEARTBEAT80 00 01 00 0B 01 05 00 01 00 03 00 80and ACKNACK80 00 01 00 0A 01 05 00 01 00 00 00 80, identical to the reference goldens shared with the other SDKs.reliable_5_3_lua_samples_arrive_in_order_despite_dropped_datagrams— the peer drops every 3rd sample once (bind_reliable_peer(Some(3))); the app the test builds from thePingthe language’s generator writes from the IDL ofcrates/endpoint-e2e/src/codegen.rs, and the loop ofreliable_app.luaretransmits on ACKNACK; all 12 samples delivered gap-free, in order, the test reads every sample by the IDL’s XCDR2 layout (assert_reliable_pings).endpoints/lua/example_reliable.luain theluacolumn oftools/endpoints-gate(jobintegration-endpoints) —example_reliable.luaruns and reportsRELIABLE OK: 12/12 delivered gap-free in 1 round(s), sequence 0..11 verified in order. Reproduced locally (lua5.5): exactly this output.
4/4 in this group (latency bench in §6).
Status: done.
§6 Producer latency — honestly: cooperative, not concurrent
Spec: §4 of the spec, honesty paragraph — AsyncWriter:push (table
insert) vs. an inline sendto, explicitly not evidence of thread
decoupling: stock lua5.4 has no native OS threads; push and drain run
on the same call stack of the same OS thread (the caller loop in
reliable_app.lua calls drain() itself — see that file’s comment). The
measurement only shows the call-cost difference between a table insert and
a UDP syscall — not concurrent processing.
Repo: endpoints/lua/reliable_app.lua function runBench — 20000
iterations of inline udp:send vs. 20000 iterations of AsyncWriter
enqueue (a plain table insert, no drain inside the timed loop); prints
BENCH enqueue_ns=... inline_send_ns=... note=cooperative_single_os_thread_no_concurrent_drain.
Tests: reliable_5_4_lua_the_producer_enqueue_costs_less_than_the_inline_send — runs reliable_app.lua mode
bench and checks that enqueue_ns of the BENCH line stays below
inline_send_ns: the call into the writer’s table against the inline send
on the same OS thread, not a concurrent decoupling.
Reproduced locally this session (lua 5.5, not lua5.4, not Linux —
a plausibility check of the mechanism, not the reference figure): 4 runs,
enqueue_ns 14–18, inline_send_ns 2829–3998 — same order of magnitude
(roughly 180–260× in this sample), the table insert clearly under the UDP
syscall, as expected for a plain call-cost difference on the same thread.
The earlier Linux/CI reference run reported enqueue ~29–32 ns / inline
~3780–4050 ns — this session did not re-run the Linux measurement, only
confirmed the local order of magnitude.
Status: done — the figure states the cost of the call, not concurrency. The spec asks for the call-cost evidence at this point; the item is met.
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-lua-1.0.md):
python3 ci/run_integration.py integration-bindings-gnat-beam(jobintegration-bindings-gnat-beam) — 4 tests green.python3 ci/run_integration.py integration-endpoints(jobintegration-endpoints) — 4 tests green.
8 cited tests green, 0 not green.
crates/endpoint-e2e/tests/lua_reliable.rs takes the same name list as
lua.rs (lua5.4, lua, lua5.3) and reports the reason loudly when none
of them or luasocket is missing.
Open items: none.
zerodds-endpoint-lua 1.0 — Spec-Coverage
Quelle: docs/specs/zerodds-endpoint-lua-1.0.md — ZeroDDS Lua
Endpoint-SDK-Spec. Das Marshalling kommt aus crates/lang-rules, Spalte Language::Lua; hier steht der Transport.
Implementation:
endpoints/lua/zerodds.lua— XRCE-Framing (writeFrame/readFrame), syncClient, coroutine-basierterasyncReader.endpoints/lua/reliable.lua— reliable Sender/Receiver-State-Machine + HEARTBEAT/ACKNACK-Wire-Codec + kooperativerAsyncWriter.endpoints/lua/reliable_app.lua— UDP-Sender-App (Modusrungegen einen Peer, Modusbenchfür den Latenz-Test).crates/endpoint-e2e/tests/lua.rs— Ping-Pong-E2E;crates/endpoint-e2e/tests/lua_reliable.rs— reliable-Stream-E2E.- Gate:
lua5.4+luasocket(dassocket-Modul) auf PATH; beides fehlend → lauter Skip, kein False-Green.
§1 XRCE-Framing
Spec: §1 — 8-Byte-XRCE-Header (session, stream, seq LE, Submsg-ID 0x07
WRITE_DATA, flags 0x03, len LE) + Body, byte-identisch zu crates/xrce +
endpoints/c.
Repo: endpoints/lua/zerodds.lua — M.writeFrame/M.readFrame,
Konstanten M.SESSION_NOKEY (0x80) und M.STREAM_BEST_EFFORT (0x01).
Tests: kein isolierter Framing-Unit-Test unabhängig vom vollen Stack;
das Framing wird über xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong/xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong (§4) live
geübt (jedes Sample durchläuft writeFrame/readFrame auf dem Draht).
Status: done.
§2 Sync Client
Spec: §2 — gepollter, nicht-blockierender Client; Write framet +
liefert synchron, Poll ist ein einzelner nicht-blockierender
Empfangsversuch; kein eingebautes Receive(timeout) — Deadline-Looping ist
Aufrufer-Sache.
Repo: endpoints/lua/zerodds.lua::Client (Client.new/Client:write/
Client:poll, session/stream-Defaults SESSION_NOKEY/
STREAM_BEST_EFFORT, monoton wachsender seq ab 1); Transport-Vertrag als
strukturelle Tabelle {deliver, receive} (kein Lua-Interface-Konstrukt).
Tests: endpoints/lua/test.lua (sync-Loopback über memTransport, Teil
der zerodds-xcdr2-lua-Coverage); Live-E2E xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§3 Async Reader (Coroutine)
Spec: §3 — asyncReader ist ein coroutine.wrap-Producer; jedes Resume
macht genau einen transport.receive()-Versuch und liefert das entrahmte
Body oder nil. Kein separater AsyncWriter für den Best-Effort-Pfad —
Schreiben bleibt Client:write, identisch für sync und async Apps; ein
echter Submit/Drain-Split existiert erst beim reliable Stream (§5), wo er
einen History-Cache und ein periodisches HEARTBEAT trägt.
Repo: endpoints/lua/zerodds.lua::M.asyncReader.
Tests: endpoints/lua/test.lua (async-Loopback über memTransport);
Live-E2E xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong (§4).
Status: done.
§4 Ping-Pong-E2E (live)
Spec: §5.1 — eine lua5.4-App tauscht mit dem geteilten Rust-XRCE-Peer
über ein echtes luasocket-UDP-Datagramm ein typisiertes Sample aus: voller
Stack (generierte zerodds-idl-lua-Typen + endpoints/lua) sowohl sync als
auch async.
Repo: crates/endpoint-e2e/tests/lua.rs — LUA_MAIN (das von
crates/endpoint-e2e/tests/lua.rs::gen_module zur Testlaufzeit als gen.lua
geschriebene Modul mit marshal_Ping/unmarshal_Pong als Globals +
require("zerodds"),
udpTransport über {deliver, receive}, Modus sync/async per
CLI-Argument, 50ms Socket-Timeout für nicht-blockierendes receive()).
Tests: crates/endpoint-e2e/tests/lua.rs — beide Fälle laufen live
gegen den Rust-XRCE-Peer über einen echten UDP-Socket:
xrce_8_3_5_8_lua_sync_app_writes_the_ping_and_reads_the_pong— voller Stack überzerodds.Client.xrce_8_3_5_8_lua_async_app_writes_the_ping_and_reads_the_pong— voller Stack überzerodds.asyncReader.
Der Harness sucht den Interpreter der Reihe nach als lua5.4, lua,
lua5.3 und überspringt hörbar (SKIP lua endpoint …), wenn keiner davon
oder luasocket fehlt; im Job integration-bindings-gnat-beam lässt eine
solche Zeile den Job scheitern.
Status: done.
§5 Reliable Stream — State-Machine, Wire, AsyncWriter
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: Sender:submit/pendingHeartbeat/
recvAcknack/getInFlight; Receiver:recvData/drainInOrder/
pendingAcknack/reset. Window 16, Receiver-Buffer 64, Heartbeat 500 ms,
Payload ≤ 65535, RFC-1982 16-bit Sequenznummern. Dazu der AsyncWriter
(push/drain) — kooperativ, nicht Thread-entkoppelt (§4 der Spec,
Ehrlichkeits-Absatz; ausführlich in §6 dieser Coverage).
Repo: endpoints/lua/reliable.lua — writeDataFrame/parseWriteData,
heartbeatFrame/parseHeartbeat, acknackFrame/parseAcknack; Sender,
Receiver; AsyncWriter (push/drain/pending/isEmpty);
endpoints/lua/example_reliable.lua (lauffähige In-Process-Demo, kein
Socket); endpoints/lua/reliable_app.lua (UDP-Sender-App, Modi run/bench).
Tests:
endpoints/lua/reliable_test.luain der Spalteluavontools/endpoints-gate(Jobintegration-endpoints) läuftlua5.4 reliable_test.lua <golden_dir>gegen die goldenen HEARTBEAT/ACKNACK-Bytes, die der Test selbst überzerodds-xrceerzeugt (dieselbe Bibliothek, die auch den Wire-Bruch anzeigen würde). Lokal nachvollzogen mitlua5.5 stattlua5.4: 48 Checks, alleok(ALL OK) — 44 State-Machine-/Frame-Roundtrip-Checks (monotoneseq, Payload-zu-groß, Window-full, Heartbeat first/silence/nach Periode, Heartbeat bei leerem Window, ACKNACK Teil-/Voll-Clear, Receiver Reorder/Dedup/Buffer-full, Pending-ACKNACK-Bitmap, Reset, End-to-End- Loss-Recovery im Speicher,AsyncWriterpush/drain inkl. Window-Cap) plus 4 Byte-Golden-Checks (endpointlua_5_byte_golden_heartbeat,endpointlua_5_byte_golden_acknack,endpointlua_5_golden_heartbeat_parse,endpointlua_5_golden_acknack_parse) — HEARTBEAT80 00 01 00 0B 01 05 00 01 00 03 00 80und ACKNACK80 00 01 00 0A 01 05 00 01 00 00 00 80, identisch zu den Referenz-Goldens der anderen SDKs.reliable_5_3_lua_samples_arrive_in_order_despite_dropped_datagrams— Peer dropt jedes 3. Sample einmalig (bind_reliable_peer(Some(3))); die App, die der Test aus demPing, den der Generator der Sprache aus der IDL voncrates/endpoint-e2e/src/codegen.rsschreibt, und der Schleife vonreliable_app.luabaut, 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).endpoints/lua/example_reliable.luain der Spalteluavontools/endpoints-gate(Jobintegration-endpoints) —example_reliable.lualäuft und meldetRELIABLE OK: 12/12 delivered gap-free in 1 round(s), sequence 0..11 verified in order. Lokal reproduziert (lua5.5): exakt diese Ausgabe.
Status: done.
§6 Producer-Latenz — ehrlich: kooperativ, nicht nebenläufig
Spec: §4 der Spec, Ehrlichkeits-Absatz — AsyncWriter:push (Tabellen-
Insert) vs. ein inline sendto, ausdrücklich kein Beleg für
Thread-Entkopplung: stock lua5.4 hat keine nativen OS-Threads; push und
drain laufen im selben Call-Stack desselben OS-Threads (der Aufrufer-Loop
in reliable_app.lua ruft drain() selbst auf, siehe dessen Kommentar).
Der Messwert zeigt nur den Call-Kosten-Unterschied Tabellen-Insert vs.
UDP-Syscall — keine parallele Verarbeitung.
Repo: endpoints/lua/reliable_app.lua Funktion runBench — 20000
Iterationen inline udp:send vs. 20000 Iterationen AsyncWriter-Enqueue
(reiner Tabellen-Insert, kein Drain in der Messschleife); Ausgabe
BENCH enqueue_ns=... inline_send_ns=... note=cooperative_single_os_thread_no_concurrent_drain.
Tests: reliable_5_4_lua_the_producer_enqueue_costs_less_than_the_inline_send — läuft reliable_app.lua Modus
bench und prüft, dass enqueue_ns der BENCH-Zeile unter
inline_send_ns liegt: der Aufruf in die Tabelle des Writers gegen den
inline Send auf demselben OS-Thread, keine nebenläufige Entkopplung.
Gemessen in diesem Lauf (macOS, lua 5.5 über den Fallback):
BENCH enqueue_ns=13 inline_send_ns=2731 note=cooperative_single_os_thread_no_concurrent_drain — Faktor ~210×,
Tabellen-Insert klar unter dem UDP-Syscall, wie für einen reinen
Call-Kosten-Unterschied auf demselben Thread erwartet. Der frühere Linux/CI-
Referenzlauf nannte enqueue ~29–32 ns / inline ~3780–4050 ns; dieser Lauf
bestätigt die Größenordnung, nicht den Referenzwert.
Status: done — der Messwert belegt die Kosten des Aufrufs, nicht die Nebenläufigkeit. Die Spec verlangt an dieser Stelle den Aufrufkostenbeleg; damit ist das Item erfüllt.
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-lua-1.0.md):
python3 ci/run_integration.py integration-bindings-gnat-beam(Jobintegration-bindings-gnat-beam) — 4 Tests grün.python3 ci/run_integration.py integration-endpoints(Jobintegration-endpoints) — 4 Tests grün.
8 zitierte Tests grün, 0 nicht grün.
crates/endpoint-e2e/tests/lua_reliable.rs nimmt dieselbe Namensliste wie
lua.rs (lua5.4, lua, lua5.3) und meldet den Grund laut, wenn keiner
davon oder luasocket fehlt.
Offene Punkte: keine.