Changelog

Copy Markdown View Source

All notable changes to moqx will be documented in this file.

[Unreleased]

[0.7.1] - 2026-04-23

Fixed

  • Fixed {:moqx_fetch_ok, ...} never being delivered to the caller when the relay drains the fetch data stream before queueing FetchOk on the control stream. handle_fetch_stream now sends {:moqx_fetch_ok, ...} immediately after reading the stream's request_id, before processing any objects.

[0.7.0] - 2026-04-23

Added

  • Added draft-14 object datagram publish/subscribe support to the core client contract via MOQX.write_datagram/3.
  • Added a subscriber-side datagram receive loop in the NIF so datagram-delivered objects are surfaced through the same {:moqx_object, %MOQX.ObjectReceived{...}} message family used for subgroup delivery.

  • Added %MOQX.Object{transport: :subgroup | :datagram} so callers can tell which delivery path produced an object without changing mailbox contracts.

  • Added relay-backed integration coverage for object datagram delivery, including transport metadata, extension round-tripping, and datagram end-of-group signaling.
  • Added %MOQX.NativeBinary{ref: reference(), size: non_neg_integer()} — a lazy payload type backed by a Rust bytes::Bytes resource. Object and fetch-object payloads now arrive as %MOQX.NativeBinary{} instead of BEAM binaries, keeping data on the native heap until the caller explicitly materialises it.
  • Added MOQX.NativeBinary.load/1 — the single copy point that materialises a NativeBinary into a BEAM binary.
  • Added MOQX.NativeBinary.from_binary/1 — wraps an existing BEAM binary into a NativeBinary for use in homogeneous-API or testing contexts.
  • MOQX.write_object/4 and MOQX.write_datagram/3 now accept either binary() or %MOQX.NativeBinary{} as the payload argument, enabling zero-copy subscribe → re-publish pipelines without touching the BEAM heap.

Changed

  • :moqx_end_of_group now explicitly covers end-of-group signaled by either a subgroup or an object datagram.
  • README and module docs now document explicit subgroup-stream vs object-datagram publishing semantics, including the fact that write_frame/2 does not auto-route to datagrams.
  • Local integration-test guidance now documents the known stale-container cert pitfall: after regenerating integration certs, the relay container must be recreated to avoid TLS handshake failures such as invalid peer certificate: BadSignature.
  • Breaking: %MOQX.Object{payload} and %MOQX.FetchObject{payload} are now MOQX.NativeBinary.t() instead of binary(). Callers that pattern-match or compare the payload field must call MOQX.NativeBinary.load/1 first.

[0.6.1] - 2026-04-16

Fixed

  • Hardened the relay-backed integration coverage for the late-publisher subscribe path so the suite no longer flakes when the current moqtail relay races an early Unknown track namespace rejection before the namespace is published. The test now retries the subscribe request within the delivery-timeout window until the late publisher appears, while still failing on unexpected subscribe errors.
  • Fixed the tag-driven release workflow's version guard to read mix.exs statically instead of invoking mix run, avoiding CI failures caused by compiler output contaminating the captured version string.

[0.6.0] - 2026-04-15

This release automates the tag-driven release path and hardens release metadata validation so publishing fails fast if the tag, mix.exs, and changelog drift.

Added

  • Added a tag-triggered GitHub Actions release workflow that reruns the full release preflight (mix format --check-formatted, mix test, mix test.integration, mix docs, and mix credo --strict) before publishing.
  • Added automated Hex publishing on v* tags via mix hex.publish --yes, using the repository HEX_API_KEY secret.
  • Added automated GitHub release creation/update on v* tags, with release notes extracted from the matching CHANGELOG.md section.
  • Added release-time validation that the pushed tag version matches both mix.exs and a CHANGELOG.md heading for the same version.

Documentation

  • Clarified project release guidance in AGENTS.md and the local release skill, including mix docs in pre-release checks.
  • Corrected the local Hex release skill to reflect actual Hex behavior: mix hex.publish publishes package + docs by default, while mix hex.publish docs remains the docs-only follow-up path.

[0.5.0] - 2026-04-15

This release finalizes the low-level async core contract that moqx exposes. MOQX is now explicitly documented as the thin async core layer, while convenience flows live in MOQX.Helpers and future stateful ergonomics remain out of the core contract.

Migration notes

If you are upgrading from older 0.2.x–0.4.x APIs:

  • connect is now explicitly correlated by connect_ref
  • publish namespace readiness is now explicit and correlated by publish_ref
  • publisher writes are lifecycle-gated and no longer silently drop before downstream activation
  • subscribe/fetch lifecycle messages now use typed structs and shared typed async error families
  • helper catalog flows moved from MOQX into MOQX.Helpers
  • unsubscribe/1 now culminates in {:moqx_publish_done, ...} rather than the old :moqx_track_ended tuple contract
  • delivery_timeout_ms remains the correct draft-14 subscribe timeout option
  • rendezvous_timeout_ms was a mistaken rename based on newer-draft terminology and should not be used on the draft-14 stack
  • local integration guidance now uses mix test.integration against a relay you keep running separately

Changed

  • Breaking: connect is now explicitly correlated. connect/2, connect_publisher/2, and connect_subscriber/2 return {:ok, connect_ref}. Asynchronous connect outcomes are delivered as typed messages: {:moqx_connect_ok, %MOQX.ConnectOk{...}}, {:moqx_request_error, %MOQX.RequestError{...}}, and {:moqx_transport_error, %MOQX.TransportError{...}}.
  • Breaking: publish namespace readiness is now explicit and correlated. publish/2 returns {:ok, publish_ref} and the broadcast handle arrives only via {:moqx_publish_ok, %MOQX.PublishOk{...}} after relay ack. Failures are delivered as typed async request/transport errors with op: :publish and the matching publish_ref.
  • Breaking: publisher write lifecycle now has explicit synchronous gating. Writes no longer silently drop before downstream activation. write_frame/2 and open_subgroup/3 now fail synchronously with typed %MOQX.RequestError{code: :track_not_active | :track_closed}.
  • Subscriber data-path race handling now tolerates early subgroup streams that arrive just before local SubscribeOk state installation, reducing first-frame loss risk under control/data-plane reordering.
  • Breaking: subgroup flush is now explicitly correlated. flush_subgroup/1 returns {:ok, flush_ref} and asynchronous completion is delivered as {:moqx_flush_ok, %MOQX.FlushDone{...}} (or typed transport failure).
  • Breaking: subscribe/fetch/object lifecycle messages now use typed payload structs and explicit message families. :moqx_subscribed/:moqx_track_ended/:moqx_fetch_started/:moqx_fetch_error tuple contracts are replaced by typed events such as :moqx_subscribe_ok, :moqx_publish_done, :moqx_fetch_ok, and the shared async error families.
  • Breaking: asynchronous generic tuple errors ({:error, reason} and {:moqx_error, ..., reason}) are no longer the primary public contract. Async failures now flow through %MOQX.RequestError{} and %MOQX.TransportError{}.
  • Added explicit publisher track lifecycle events for track owners: {:moqx_track_active, %MOQX.TrackActive{...}} and {:moqx_track_closed, %MOQX.TrackClosed{...}}.
  • Breaking: helper-level convenience APIs moved out of core MOQX into MOQX.Helpers (publish_catalog/2, update_catalog/2, fetch_catalog/2, await_catalog/2).
  • Mix tasks now expose primary names moqx.roundtrip and moqx.inspect. Legacy aliases moqx.e2e.pubsub and moqx.moqtail.demo remain available with deprecation notices.
  • moqx.inspect can probe catalog tracks named either "catalog" or ".catalog" (or an explicit --catalog-track), supports --no-fetch for relays that do not implement fetch yet, and now includes named relay presets plus interactive preset selection. This improves interop with Cloudflare moq-rs style relays and other early deployments.
  • MOQX.Helpers.fetch_catalog/2 now accepts :track so callers can override the catalog track name when relays do not use "catalog".
  • Mix tasks and integration helpers now follow the typed async contract.
  • Integration tests now assume a relay endpoint provided by environment (MOQX_EXTERNAL_RELAY_URL) and trusted CA path (MOQX_RELAY_CACERTFILE), with Docker-based local/CI orchestration as the primary deterministic path.
  • Removed :public_relay_live integration tests; public relay interop checks now live in manual mix tasks.
  • Subscribe request rejections now carry typed RequestError.code values (for example :track_does_not_exist / :timeout).
  • Corrected subscribe-timeout naming/docs back to draft-14 delivery_timeout_ms after auditing the wire parameter mapping against the spec and moqtail.
  • Pinned README spec references to the explicit draft-14 target instead of the moving latest Internet-Draft URL.
  • Hardened the early-subscribe integration coverage to use a short payload burst rather than assuming the very first write always survives the current moqtail relay's subscribe-activation race window.

Documentation

  • Rewrote README and module docs to align with the low-level async contract and remove stale tuple-era examples (:moqx_frame, :moqx_subscribed, :moqx_track_ended, :moqx_error, etc.).
  • Clarified core vs helper-layer responsibilities and the intended separation from any future managed/stateful ergonomics layer.
  • Added 0.5.0 migration guidance covering message-shape, lifecycle, helper, timeout-option, and integration-harness changes.
  • Documented current moqtail standalone fetch behavior more explicitly: relay-backed fetch succeeds from relay cache, while cache misses surface as typed fetch request errors rather than hanging silently.
  • Clarified core async message families and correlation behavior for connect, subscribe, fetch, and subgroup flush.

[0.4.1] - 2026-04-12

Fixed

  • MOQX.unsubscribe/1 and subscription handle Drop no longer panic the NIF with send_and_clear: current thread is managed. Environment work (message send to the caller) is now performed inside the Tokio runtime instead of on the BEAM scheduler thread invoking the NIF/GC.
  • Added end-to-end integration coverage for unsubscribe/1 (live relay roundtrip verifying :moqx_track_ended, frame cut-off, and idempotent double-unsubscribe).

[0.4.0] - 2026-04-12

Added

  • MOQX.unsubscribe/1 cancels an active track subscription by sending MOQ Unsubscribe to the relay. Idempotent and fire-and-forget; the caller subsequently receives {:moqx_track_ended, handle} when the relay acknowledges.
  • Dropping a subscription handle (GC) now automatically cancels the subscription — short-lived subscribing processes no longer need to unsubscribe explicitly to free relay-side resources.
  • {:moqx_track_ended, handle} is now emitted on publisher-side PublishDone (graceful TrackEnded / SubscriptionEnded status codes). The corresponding local subscription state is removed in the same path, fixing a small leak in active_subscriptions.
  • MOQX.Helpers.publish_catalog/2 helper to create and publish the initial "catalog" track object.
  • MOQX.Helpers.update_catalog/2 helper to publish subsequent catalog objects.
  • Integration E2E coverage that verifies publisher-provided catalog objects are relayed downstream.

Changed

  • Breaking: MOQX.subscribe/3,4 and MOQX.subscribe_track/3,4 now return an opaque subscription handle (Rustler resource) instead of a bare make_ref(). Pattern-matching and is_reference/1 continue to work; callers that depended on make_ref() semantics (serialization, external storage) need to adapt.
  • README and module docs now explicitly document the publisher-driven catalog flow used with moqtail-style relays.

[0.3.0] - 2026-04-09

Added

  • MOQX.subscribe_track/3,4 convenience API for catalog-driven subscriptions.
  • Track metadata helpers on MOQX.Catalog.Track:
    • explicit_metadata/1
    • inferred_metadata/1
    • extra_metadata/1
    • describe/1
  • New relay debug task mix moqx.moqtail.demo (catalog listing, interactive selection, runtime stats, catalog fallback behavior).

Changed

  • Breaking subscription contract now returns and propagates subscription_ref:
    • subscribe/3,4 now return {:ok, sub_ref}.
    • subscription messages now include sub_ref.
  • Breaking subscription lifecycle now emits {:moqx_track_init, sub_ref, init_data, track_meta} once per subscription.
  • Integration/E2E tasks and tests updated for the new subscription correlation model.
  • README/docs/examples updated for the new API and task naming.

[0.2.1] - 2026-04-09

Added

  • mix moqx.e2e.pubsub task for end-to-end publisher/subscriber relay smoke testing.
  • README examples for running relay E2E smoke tests, including Cloudflare draft-14 relay endpoints.

Changed

  • integration test tagging split to keep CI deterministic (:integration) while keeping live public relay coverage opt-in (:public_relay_live).
  • mix test.integration now excludes :public_relay_live tests by default.

[0.2.0] - 2026-04-08

First release of the current Rustler + moqtail-rs based Elixir MOQ client library line.

Added

  • CMSF catalog decoding and media track discovery via MOQX.Catalog
  • raw fetch and catalog retrieval APIs for subscriber sessions
  • validated relay-backed integration coverage for v14/v17 interop and live relay behavior

Changed

  • native integration migrated to moqtail-rs
  • publish flow aligned around PublishNamespace behavior
  • docs and examples updated for the current client contract

Notes

  • moqx on Hex had prior unrelated releases; 0.2.0 marks this project line as the canonical continuation.

[0.1.0] - 2026-03-30

Initial public client release.

Added

  • explicit split-role client API with connect_publisher/1,2, connect_subscriber/1,2, and connect/2
  • Quinn-backed transport support for :auto, :raw_quic, :webtransport, and :websocket
  • secure-by-default client TLS controls with optional custom root CA support and explicit local-dev insecure mode
  • relay-authenticated client flows using rooted ?jwt=... URLs
  • relay-backed integration coverage for transport parity, TLS behavior, and authenticated rooted-path flows
  • CI split between fast checks and relay-backed integration coverage

Changed

  • public docs now freeze the supported v0.1 client contract and async message/error expectations
  • package metadata now includes Hex-oriented description, license, source, changelog, and docs configuration