Integrate picoquic build path and docs

Author: mondain

CMakeLists.txt

@@ -10,13 +10,43 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
 option(OPENMOQ_BUILD_TESTS "Build OpenMOQ publisher tests" ON)
+option(OPENMOQ_ENABLE_PICOQUIC "Enable picoquic transport integration when picoquic is available" ON)
+option(OPENMOQ_RUN_PICOQUIC_SMOKE_TESTS "Build and run picoquic loopback smoke tests" OFF)
+
+set(OPENMOQ_PICOQUIC_SOURCE_DIR "/media/mondain/terrorbyte/workspace/github/picoquic" CACHE PATH
+    "Path to a picoquic source checkout")
+
+set(OPENMOQ_HAS_PICOQUIC OFF)
+
+if(OPENMOQ_ENABLE_PICOQUIC AND EXISTS "${OPENMOQ_PICOQUIC_SOURCE_DIR}/CMakeLists.txt")
+    set(OPENMOQ_PICOTLS_SOURCE_DIR "${OPENMOQ_PICOQUIC_SOURCE_DIR}/../picotls" CACHE PATH
+        "Path to a picotls source checkout")
+
+    if(EXISTS "${OPENMOQ_PICOTLS_SOURCE_DIR}/CMakeLists.txt")
+        set(PICOQUIC_FETCH_PTLS ON CACHE BOOL "" FORCE)
+        set(FETCHCONTENT_SOURCE_DIR_PICOTLS "${OPENMOQ_PICOTLS_SOURCE_DIR}" CACHE PATH "" FORCE)
+        set(picoquic_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+        set(BUILD_DEMO OFF CACHE BOOL "" FORCE)
+        set(BUILD_HTTP OFF CACHE BOOL "" FORCE)
+        set(BUILD_PQBENCH OFF CACHE BOOL "" FORCE)
+        set(BUILD_LOGLIB OFF CACHE BOOL "" FORCE)
+        set(BUILD_LOGREADER OFF CACHE BOOL "" FORCE)
+        add_subdirectory("${OPENMOQ_PICOQUIC_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/picoquic")
+        set(OPENMOQ_HAS_PICOQUIC ON)
+    else()
+        message(STATUS "picoquic checkout found, but picotls source was not found; building without picoquic integration")
+    endif()
+endif()
 
 add_library(openmoq_publisher_lib
     src/cli_options.cpp
     src/cmaf_segmenter.cpp
     src/cmsf_packager.cpp
     src/moq_draft.cpp
     src/mp4_box.cpp
+    src/transport/moqt_session.cpp
+    src/transport/picoquic_client.cpp
+    src/transport/publisher_transport.cpp
 )
 
 target_include_directories(openmoq_publisher_lib
@@ -26,6 +56,11 @@ target_include_directories(openmoq_publisher_lib
 
 target_compile_features(openmoq_publisher_lib PUBLIC cxx_std_20)
 
+if(OPENMOQ_HAS_PICOQUIC)
+    target_compile_definitions(openmoq_publisher_lib PRIVATE OPENMOQ_HAS_PICOQUIC=1)
+    target_link_libraries(openmoq_publisher_lib PRIVATE picoquic-core)
+endif()
+
 if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
     target_compile_options(openmoq_publisher_lib PRIVATE -Wall -Wextra -Wpedantic)
 endif()
@@ -36,9 +71,26 @@ target_link_libraries(openmoq-publisher PRIVATE openmoq_publisher_lib)
 include(CTest)
 
 if(OPENMOQ_BUILD_TESTS)
-    add_executable(openmoq-publisher-tests
+    add_executable(openmoq-publisher-packaging-tests
         tests/cmaf_segmenter_test.cpp
     )
-    target_link_libraries(openmoq-publisher-tests PRIVATE openmoq_publisher_lib)
-    add_test(NAME openmoq-publisher-tests COMMAND openmoq-publisher-tests)
+    target_link_libraries(openmoq-publisher-packaging-tests PRIVATE openmoq_publisher_lib)
+    add_test(NAME openmoq-publisher-packaging-tests COMMAND openmoq-publisher-packaging-tests)
+
+    add_executable(openmoq-publisher-transport-tests
+        tests/moqt_session_test.cpp
+    )
+    target_link_libraries(openmoq-publisher-transport-tests PRIVATE openmoq_publisher_lib)
+    add_test(NAME openmoq-publisher-transport-tests COMMAND openmoq-publisher-transport-tests)
+
+    if(OPENMOQ_HAS_PICOQUIC AND OPENMOQ_RUN_PICOQUIC_SMOKE_TESTS)
+        add_executable(openmoq-publisher-picoquic-smoke-tests
+            tests/picoquic_smoke_test.cpp
+        )
+        target_link_libraries(openmoq-publisher-picoquic-smoke-tests PRIVATE openmoq_publisher_lib)
+        target_include_directories(openmoq-publisher-picoquic-smoke-tests PRIVATE
+            "${OPENMOQ_PICOQUIC_SOURCE_DIR}/picoquic"
+        )
+        add_test(NAME openmoq-publisher-picoquic-smoke-tests COMMAND openmoq-publisher-picoquic-smoke-tests)
+    endif()
 endif()

README.md

@@ -60,16 +60,66 @@ This keeps the project aligned with CMAF-style publication while avoiding unnece
 - `src`: library and CLI implementation
 - `tests`: CTest-based unit coverage
 - `docs`: protocol notes and design references
+- `docs/transport-plan.md`: picoquic integration plan and implementation checklist
 - `.github/workflows/ci.yml`: GitHub Actions build and test workflow for Linux and macOS
 
 ## Build
 
+### Baseline build
+
+This is the default path if you only want the packaging and session-layer code:
+
+```bash
+cmake -S . -B build -DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=OFF
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+### Build with local picoquic and picotls
+
+If you have local checkouts at:
+
+- `/media/mondain/terrorbyte/workspace/github/picoquic`
+- `/media/mondain/terrorbyte/workspace/github/picotls`
+
+then the project will automatically compile against them.
+
+Required picotls setup:
+
 ```bash
-cmake -S . -B build
+git -C /media/mondain/terrorbyte/workspace/github/picotls submodule update --init --recursive
+```
+
+Then configure and build normally:
+
+```bash
+cmake -S . -B build -DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=OFF
 cmake --build build
 ctest --test-dir build --output-on-failure
 ```
 
+Useful CMake options:
+
+- `-DOPENMOQ_ENABLE_PICOQUIC=ON|OFF`
+- `-DOPENMOQ_PICOQUIC_SOURCE_DIR=/path/to/picoquic`
+- `-DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=ON|OFF`
+
+### Optional picoquic smoke test
+
+There is an in-repo loopback smoke test target for the picoquic transport path, but it is disabled by default:
+
+```bash
+cmake -S . -B build -DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=ON
+cmake --build build --target openmoq-publisher-picoquic-smoke-tests
+ctest --test-dir build --output-on-failure
+```
+
+Current status:
+
+- the smoke test compiles
+- the end-to-end loopback handshake currently times out
+- keep this option off for routine development until that runtime issue is fixed
+
 ## Usage
 
 Inspect the publish plan for an already fragmented MP4:
@@ -90,6 +140,23 @@ Try the draft-16 compatibility profile:
 ./build/openmoq-publisher --input sample.mp4 --draft 16 --dump-plan
 ```
 
+Transport-oriented CLI flags are also present now:
+
+```bash
+./build/openmoq-publisher \
+  --input sample.mp4 \
+  --endpoint localhost:4433 \
+  --alpn moqt \
+  --insecure
+```
+
+Current status:
+
+- the packaging pipeline is fully usable today
+- the session and transport interfaces are now scaffolded in code
+- `--endpoint` now enters the real picoquic-backed transport path when the project is built with local picoquic and picotls support
+- the compile-time transport integration works, but live handshake validation is still incomplete
+
 ## Creating Fragmented MP4 with FFmpeg
 
 The publisher’s preferred fast path is already fragmented MP4 input. You can generate that with `ffmpeg` by copying compatible AAC-LC or H.264 streams and enabling CMAF-style fragmentation flags:
@@ -128,6 +195,15 @@ GitHub Actions is configured to build and test the project on:
 
 The workflow currently runs the same CMake configure, build, and CTest steps on both platforms.
 
+## Picoquic status
+
+The repository now includes a transport abstraction and a picoquic-backed client wrapper.
+
+- if local picoquic and picotls source trees are available, CMake can compile the real picoquic transport path into this project
+- if those dependencies are not available, the project still builds and tests normally, and the transport layer falls back cleanly
+- in this workspace, picoquic and picotls compile successfully as subprojects
+- the remaining transport issue is runtime: the loopback smoke test handshake still times out
+
 ## Contributing
 
 See [CONTRIBUTING.md](/media/mondain/terrorbyte/workspace/github/moqxr/CONTRIBUTING.md) for contribution expectations and development notes.

docs/transport-plan.md

@@ -0,0 +1,163 @@
+# Picoquic Transport Plan
+
+This document turns the current picoquic integration idea into an implementation checklist for `moqxr`.
+
+## Goal
+
+Add a native QUIC transport layer using picoquic so the existing publisher pipeline can send MOQT control and media objects over a real connection without rewriting the packaging code.
+
+## Scope boundaries
+
+The current repository already handles:
+
+- MP4 parsing
+- fragmented MP4 fast-path packaging
+- progressive MP4 remux into synthetic fragments
+- draft-aware publish planning
+
+The picoquic work should add:
+
+- QUIC connection management
+- MOQT session setup and control streams
+- media object publication over QUIC streams
+- transport-level backpressure and error handling
+
+The picoquic work should not initially add:
+
+- HTTP/3
+- WebTransport
+- broad muxing or repackaging logic
+- advanced QUIC features such as migration or multipath
+
+## Architecture target
+
+The intended layering is:
+
+1. Packaging layer
+   Uses `ParsedMp4`, `SegmentedMp4`, and `PublishPlan`.
+2. Session layer
+   Converts a `PublishPlan` into MOQT control and object publication actions.
+3. Transport layer
+   Provides connection, stream, and write primitives.
+4. Picoquic adapter
+   Implements the transport layer on top of picoquic callbacks and sockets.
+
+This separation is important because MOQT draft churn should be isolated to the session layer, while picoquic remains a byte transport.
+
+## Deliverables
+
+### Phase 1: transport seam
+
+- [x] Add a transport interface for connect, open stream, write, close
+- [x] Add a session façade that consumes `PublishPlan`
+- [x] Add a picoquic client stub that implements the transport interface
+- [x] Keep current CLI and packaging flow unchanged
+
+### Phase 2: connection establishment
+
+- [x] Add endpoint configuration: host, port, ALPN
+- [x] Add TLS configuration hooks: cert, key, CA, insecure-dev toggle
+- [x] Establish a client QUIC connection with picoquic
+- [x] Report handshake success and failures cleanly
+
+### Phase 3: MOQT control plane
+
+- [ ] Open a control stream after handshake
+- [ ] Implement setup and session negotiation
+- [ ] Implement namespace or publish announcement flow
+- [ ] Represent draft-14 and draft-16 control-plane differences behind one abstraction
+
+### Phase 4: object publication
+
+- [ ] Publish initialization object first
+- [ ] Publish media objects according to `PublishPlan`
+- [ ] Decide and document one stream mapping policy
+- [ ] Handle transport write backpressure
+
+### Phase 5: observability and testing
+
+- [ ] Add structured logs for handshake, stream lifecycle, and object publication
+- [ ] Add unit tests for session-to-transport mapping
+- [ ] Add loopback integration tests for transport
+- [ ] Add interoperability tests against an OpenMOQ-capable endpoint
+
+## Proposed stream mapping
+
+Initial recommendation:
+
+- one bidirectional control stream per session
+- one unidirectional stream per published object in the first implementation
+
+That policy is not necessarily optimal long-term, but it is easier to reason about and validate while the control-plane logic is still moving.
+
+## Interface responsibilities
+
+### `PublisherTransport`
+
+Owns:
+
+- connection establishment
+- stream creation
+- byte writes
+- close
+- connection state
+
+Does not own:
+
+- MOQT message structure
+- media packaging
+- object scheduling policy
+
+### `MoqtSession`
+
+Owns:
+
+- setup and control-plane sequencing
+- draft-specific control behavior
+- translation from `PublishPlan` to transport actions
+
+Does not own:
+
+- raw QUIC callbacks
+- MP4 parsing
+- object bytes
+
+### `PicoquicClient`
+
+Owns:
+
+- picoquic configuration and lifecycle
+- callback bridging
+- stream IDs and write execution
+- error translation into transport-level status objects
+
+## Suggested implementation order
+
+1. Land interface-only scaffolding
+2. Add endpoint and TLS config types
+3. Implement a connect-only picoquic client
+4. Add control stream bring-up
+5. Add init object publication
+6. Add full object publication from `PublishPlan`
+7. Add retry, backpressure, and metrics
+
+## Current repository status
+
+- The transport seam and session façade are implemented.
+- CLI flags for endpoint, ALPN, and TLS-related parameters are present.
+- The build can integrate local picoquic and picotls source checkouts directly.
+- The current workspace now compiles picoquic and picotls successfully.
+- A loopback smoke test was added for live handshake validation, but it is not enabled by default because the current handshake attempt still times out.
+
+## Key risks
+
+- draft-14 vs draft-16 control differences leaking into transport code
+- coupling picoquic callback state too tightly to publish scheduling
+- under-specifying how objects map to streams early on
+
+## Mitigations
+
+- keep draft-specific message encoding in session code
+- keep transport status and callbacks generic
+- start with a conservative one-object-per-stream policy
+- add integration tests before optimizing stream reuse or pacing

include/openmoq/publisher/cli_options.h

@@ -5,12 +5,15 @@
 #include <string>
 
 #include "openmoq/publisher/moq_draft.h"
+#include "openmoq/publisher/transport/publisher_transport.h"
 
 namespace openmoq::publisher {
 
 struct CliOptions {
     std::filesystem::path input_path;
     std::optional<std::filesystem::path> emit_dir;
+    std::optional<transport::EndpointConfig> endpoint;
+    transport::TlsConfig tls;
     DraftVersion draft_version = DraftVersion::kDraft14;
     bool dump_plan = false;
 };

include/openmoq/publisher/cmsf_packager.h

@@ -32,6 +32,7 @@ struct PublishPlan {
 
 PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion version);
 std::string render_publish_plan(const PublishPlan& plan);
+PublishPlan materialize_publish_plan(const PublishPlan& plan, std::span<const std::uint8_t> bytes);
 void emit_plan_objects(const PublishPlan& plan,
                        std::span<const std::uint8_t> bytes,
                        const std::filesystem::path& output_dir);