diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt index 7851685616..bafa5c8a6b 100644 --- a/src/core/CMakeLists.txt +++ b/src/core/CMakeLists.txt @@ -26,6 +26,7 @@ add_subdirectory(camera_core) if(CMAKE_SYSTEM_NAME STREQUAL "Linux") add_subdirectory(camera_ipc) add_subdirectory(camera_wire) + add_subdirectory(camera_endpoint) endif() # Build OXR library (depends on oxr_utils for types) diff --git a/src/core/camera_endpoint/AGENTS.md b/src/core/camera_endpoint/AGENTS.md new file mode 100644 index 0000000000..92ff196bc1 --- /dev/null +++ b/src/core/camera_endpoint/AGENTS.md @@ -0,0 +1,15 @@ + + +# Agent notes — `camera_endpoint` + +**CRITICAL (non-optional):** Before editing this package, complete the mandatory **`AGENTS.md` preflight** in [`../../../AGENTS.md`](../../../AGENTS.md) (read every applicable `AGENTS.md` on your paths, not just this file). + +Read [`README.md`](README.md) for what runs on which thread before changing it. + +- **Nothing sits between publish and the socket.** A frame event is encoded and sent inside `send_event`, on the publishing thread. Do not add a queue or a thread hop there, and do not log per frame. +- **`send_event` holds the publisher's lock.** It must not take another lock, block or call the publisher. That lock is also what serialises each connection's event encoder. +- **Unsubscribe before a connection is destroyed.** `Publisher::unsubscribe` returning is the guarantee that no `send_event` is running or will start for that sink. +- **A reader is untrusted.** Whatever it sends can at most get it dropped; it must not stop the thread or affect other readers. diff --git a/src/core/camera_endpoint/CMakeLists.txt b/src/core/camera_endpoint/CMakeLists.txt new file mode 100644 index 0000000000..8ce91de360 --- /dev/null +++ b/src/core/camera_endpoint/CMakeLists.txt @@ -0,0 +1,6 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +add_subdirectory(cpp) diff --git a/src/core/camera_endpoint/README.md b/src/core/camera_endpoint/README.md new file mode 100644 index 0000000000..a32ab763c4 --- /dev/null +++ b/src/core/camera_endpoint/README.md @@ -0,0 +1,49 @@ + + +# Camera interface: the endpoint + +The camera plugin's side of the conversation with readers. It puts a +[`camera_core`](../camera_core) `Publisher` on a socket ([`camera_ipc`](../camera_ipc)) and +speaks the messages of [`camera_wire`](../camera_wire). + +```cpp +Publisher publisher; +const GroupId head = publisher.add_group(description); +HostPool left(slots, bytes, "head.left"), right(slots, bytes, "head.right"); + +Endpoint endpoint(publisher, socket_path); +endpoint.set_group_memory(head, { left.descriptor(), right.descriptor() }); +endpoint.start(); +// ... the backend acquires slots, writes pixels and publishes; readers come and go ... +``` + +## What runs where + +- **One thread of its own** accepts readers and handles what they send: the handshake, + subscriptions and releases. It sleeps in `poll` until a reader sends something. +- **Frame events are sent from the thread that publishes**, straight from + `Publisher::publish`, with a send that does not block. There is no queue and no hand-over + to another thread between a frame set being published and its event being on the socket. + The event that follows a release is sent from the endpoint's thread for the same reason. +- A reader's subscription takes effect before the answer to it is sent, so a `Frame` can + reach the reader ahead of `Subscribed`. + +## When a reader goes away + +A closed connection is the signal, whether the reader exited, crashed or was killed. Its +subscription ends and every frame set it held goes back to the pool. A reader that sends +bytes that are not a message, or a message only a plugin sends, is dropped the same way; +other readers are not affected. + +## Logging + +`isaaccapture.camera_endpoint.Endpoint` logs readers arriving, subscribing, being refused and +leaving. Nothing is logged per frame. + +## Tests + +`tests/cpp/core/camera_endpoint`, run with `ctest -L camera_endpoint`. They are tagged `unit` +and play the reader's part with the socket and the codec directly. diff --git a/src/core/camera_endpoint/cpp/CMakeLists.txt b/src/core/camera_endpoint/cpp/CMakeLists.txt new file mode 100644 index 0000000000..4bcdfb1e78 --- /dev/null +++ b/src/core/camera_endpoint/cpp/CMakeLists.txt @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +# The plugin's side of the conversation with readers: serves a Publisher's groups over a socket. +add_library(camera_endpoint STATIC + endpoint.cpp +) + +target_include_directories(camera_endpoint INTERFACE + $ +) + +target_link_libraries(camera_endpoint + PUBLIC + camera::camera_core + PRIVATE + camera::camera_ipc + camera::camera_wire + log_bridge::log_bridge_core + Threads::Threads +) + +add_library(camera::camera_endpoint ALIAS camera_endpoint) diff --git a/src/core/camera_endpoint/cpp/endpoint.cpp b/src/core/camera_endpoint/cpp/endpoint.cpp new file mode 100644 index 0000000000..652a06afaf --- /dev/null +++ b/src/core/camera_endpoint/cpp/endpoint.cpp @@ -0,0 +1,406 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/camera_endpoint/endpoint.hpp" + +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace core::camera +{ + +namespace +{ + +// One reader. As an EventSink it is called by the publisher, on whichever thread publishes or +// releases, with the publisher's lock held; everything else runs on the endpoint's thread. +class Connection final : public EventSink +{ +public: + explicit Connection(MessageSocket connected) : socket(std::move(connected)) + { + } + + bool send_event(SubscriptionId /*subscription*/, const FrameEvent& event) noexcept override + { + try + { + return socket.send(m_event_encoder.encode(event)) == SendStatus::SENT; + } + catch (const std::exception&) + { + return false; // the reader gets a later frame set, or its closed socket is noticed + } + } + + MessageSocket socket; + std::string name = "unnamed"; + bool greeted = false; + SubscriptionId subscription = 0; + +private: + WireEncoder m_event_encoder; // used inside send_event only, which the publisher's lock serialises +}; + +const char* name_of(DeliveryOrder order) +{ + switch (order) + { + case DeliveryOrder::NEWEST: + return "newest"; + case DeliveryOrder::IN_ORDER: + return "in order"; + default: + return "default order"; + } +} + +} // namespace + +class Endpoint::Impl +{ +public: + Impl(Publisher& publisher, const std::string& path) + : m_publisher(publisher), + m_path(path), + m_listener(std::in_place, path), + m_wake(::eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK)), + m_buffer(MAX_WIRE_MESSAGE_BYTES), + m_logger(isaaccapture::Logger::get("isaaccapture.camera_endpoint.Endpoint")) + { + if (!m_wake.valid()) + { + throw std::system_error(errno, std::generic_category(), "creating the camera endpoint's wake-up descriptor"); + } + } + + ~Impl() + { + stop(); + } + + void set_group_memory(GroupId group, std::vector descriptors) + { + if (m_thread.joinable()) + { + throw std::logic_error("a camera group's memory is named before the endpoint starts"); + } + const GroupDescription description = m_publisher.group_description(group); + if (descriptors.size() != description.streams.size()) + { + throw std::invalid_argument("camera group '" + description.id + "' needs one descriptor per stream"); + } + m_memory[group] = std::move(descriptors); + } + + void start() + { + if (m_thread.joinable()) + { + return; + } + if (!m_listener) + { + m_listener.emplace(m_path); + } + m_stopping = false; + m_thread = std::thread([this] { run(); }); + m_logger->info("serving cameras on '{}'", m_path); + } + + void stop() + { + if (!m_thread.joinable()) + { + return; + } + m_stopping = true; + const std::uint64_t one = 1; + // Cannot fail in a way that matters: the counter only overflows after 2^64 wake-ups. + [[maybe_unused]] const ssize_t written = ::write(m_wake.get(), &one, sizeof(one)); + m_thread.join(); + // Without the listener a reader that tries to connect is refused at once, instead of + // waiting in a queue nobody serves. + m_listener.reset(); + } + + std::size_t reader_count() const + { + return m_reader_count.load(); + } + +private: + void run() + { + std::vector waits; + while (!m_stopping) + { + waits.assign({ { m_wake.get(), POLLIN, 0 }, { m_listener->descriptor(), POLLIN, 0 } }); + for (const auto& connection : m_connections) + { + waits.push_back({ connection->socket.descriptor(), POLLIN, 0 }); + } + if (::poll(waits.data(), waits.size(), -1) < 0) + { + if (errno == EINTR) + { + continue; + } + m_logger->error("camera endpoint stops serving: poll failed with errno {}", errno); + break; + } + + // Back to front, so dropping a connection leaves the indices still to visit alone. + for (std::size_t i = m_connections.size(); i-- > 0;) + { + if (waits[i + 2].revents != 0 && !serve(*m_connections[i])) + { + drop(i); + } + } + if ((waits[1].revents & POLLIN) != 0) + { + accept_readers(); + } + } + while (!m_connections.empty()) + { + drop(m_connections.size() - 1); + } + // Empty the wake-up counter, so that serving can start again. + std::uint64_t wakes = 0; + [[maybe_unused]] const ssize_t drained = ::read(m_wake.get(), &wakes, sizeof(wakes)); + } + + void accept_readers() + { + try + { + while (auto socket = m_listener->accept(std::chrono::milliseconds(0))) + { + m_connections.push_back(std::make_unique(std::move(*socket))); + m_reader_count = m_connections.size(); + } + } + catch (const std::exception& error) + { + m_logger->warn("could not accept a camera reader: {}", error.what()); + } + } + + // Ends the reader's subscription before its sink goes away. unsubscribe() returns only once + // no send_event is running or can start for it. + void drop(std::size_t index) + { + Connection& connection = *m_connections[index]; + if (connection.subscription != 0) + { + m_publisher.unsubscribe(connection.subscription); + } + m_logger->info("camera reader '{}' is gone", connection.name); + m_connections.erase(m_connections.begin() + static_cast(index)); + m_reader_count = m_connections.size(); + } + + // Handles everything the reader has sent. Returns false when the connection is to be dropped. + bool serve(Connection& connection) + { + try + { + for (;;) + { + const ReceivedMessage received = connection.socket.receive(m_buffer, std::chrono::milliseconds(0)); + if (received.status == ReceiveStatus::TIMEOUT) + { + return true; + } + if (received.status == ReceiveStatus::CLOSED) + { + return false; + } + const WireMessage message = decode_wire_message({ m_buffer.data(), received.bytes }); + if (!handle(connection, message)) + { + return false; + } + } + } + catch (const std::exception& error) + { + m_logger->warn("dropping camera reader '{}': {}", connection.name, error.what()); + return false; + } + } + + bool handle(Connection& connection, const WireMessage& message) + { + if (const auto* hello = std::get_if(&message)) + { + return greet(connection, *hello); + } + if (const auto* subscribe = std::get_if(&message)) + { + if (!connection.greeted) + { + m_logger->warn("dropping a camera reader that subscribed before it said hello"); + return false; + } + return answer(connection, *subscribe); + } + if (const auto* release = std::get_if(&message)) + { + if (connection.subscription != 0) + { + m_publisher.release(connection.subscription, release->lease_id); + } + return true; + } + if (std::holds_alternative(message)) + { + return true; // from a newer reader; not for this build + } + m_logger->warn("dropping camera reader '{}': it sent a message only a plugin sends", connection.name); + return false; + } + + bool greet(Connection& connection, const HelloMessage& hello) + { + connection.name = hello.reader_name.empty() ? "unnamed" : hello.reader_name; + WelcomeMessage welcome; + if (hello.protocol_version != WIRE_PROTOCOL_VERSION) + { + welcome.error = "this camera plugin speaks protocol version " + std::to_string(WIRE_PROTOCOL_VERSION) + + " and the reader version " + std::to_string(hello.protocol_version); + m_logger->warn("refusing camera reader '{}': {}", connection.name, welcome.error); + (void)send(connection, m_encoder.encode(welcome)); + return false; + } + const std::size_t group_count = m_publisher.group_count(); + for (std::size_t i = 0; i < group_count; ++i) + { + welcome.groups.push_back(m_publisher.group_description(static_cast(i))); + } + connection.greeted = true; + m_logger->info("camera reader '{}' connected", connection.name); + return send(connection, m_encoder.encode(welcome)); + } + + bool answer(Connection& connection, const SubscribeMessage& subscribe) + { + SubscribedMessage reply; + std::span descriptors; + const std::optional group = m_publisher.find_group(subscribe.group); + if (connection.subscription != 0) + { + reply.error = "a connection carries one subscription; open another connection for a second group"; + } + else if (!group) + { + reply.error = "the camera plugin publishes no group '" + subscribe.group + "'"; + } + else if (!m_memory.contains(*group)) + { + reply.error = "camera group '" + subscribe.group + "' has no memory a reader can map"; + } + else + { + // From here on the publisher may send this reader frame events at any moment, so a + // Frame can reach it before the Subscribed below. + const SubscribeResult result = m_publisher.subscribe(connection, *group, subscribe.options); + if (result) + { + connection.subscription = result.id; + reply.group = m_publisher.group_description(*group); + descriptors = m_memory.at(*group); + } + else + { + reply.error = result.error; + } + } + + if (reply.error.empty()) + { + m_logger->info("camera reader '{}' subscribed to '{}' (window {}, {})", connection.name, subscribe.group, + subscribe.options.window, name_of(subscribe.options.order)); + } + else + { + m_logger->warn("refusing camera reader '{}': {}", connection.name, reply.error); + } + return send(connection, m_encoder.encode(reply), descriptors); + } + + static bool send(Connection& connection, std::span bytes, std::span descriptors = {}) + { + return connection.socket.send(bytes, descriptors) == SendStatus::SENT; + } + + Publisher& m_publisher; + std::string m_path; + std::optional m_listener; // absent between stop() and the next start() + UniqueFd m_wake; + std::map> m_memory; + + std::thread m_thread; + std::atomic m_stopping{ false }; + std::atomic m_reader_count{ 0 }; + + // The endpoint's thread only. + std::vector> m_connections; + std::vector m_buffer; + WireEncoder m_encoder; + + std::shared_ptr m_logger; +}; + +Endpoint::Endpoint(Publisher& publisher, const std::string& path) : m_impl(std::make_unique(publisher, path)) +{ +} + +Endpoint::~Endpoint() = default; + +void Endpoint::set_group_memory(GroupId group, std::vector descriptors) +{ + m_impl->set_group_memory(group, std::move(descriptors)); +} + +void Endpoint::start() +{ + m_impl->start(); +} + +void Endpoint::stop() +{ + m_impl->stop(); +} + +std::size_t Endpoint::reader_count() const +{ + return m_impl->reader_count(); +} + +} // namespace core::camera diff --git a/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp new file mode 100644 index 0000000000..7183340c5a --- /dev/null +++ b/src/core/camera_endpoint/cpp/inc/camera_endpoint/endpoint.hpp @@ -0,0 +1,70 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include + +#include +#include +#include +#include + +namespace core::camera +{ + +/** + * @brief Serves a Publisher's groups to readers in other processes. + * + * Listens on a socket file. Each reader is told what is published; when it subscribes it is + * sent the group's pool descriptors and from then on the group's frame events. A reader that + * goes away, cleanly or not, has every frame set it held taken back. + */ +class Endpoint +{ +public: + /** + * @brief Start listening on `path`. Readers are answered once start() has been called. + * @param publisher Must outlive the endpoint. + * @throws std::system_error if another process listens on the path or it cannot be bound. + */ + Endpoint(Publisher& publisher, const std::string& path); + + // Stops serving. + ~Endpoint(); + + Endpoint(const Endpoint&) = delete; + Endpoint& operator=(const Endpoint&) = delete; + + /** + * @brief Name what a reader maps for a group: one descriptor per stream, in stream order, + * for the stream's pool. The endpoint does not own them; they stay open while it serves. + * A group without them cannot be subscribed to. + * @throws std::logic_error after start(). + * @throws std::out_of_range for a group the publisher does not have. + * @throws std::invalid_argument if the count does not match the group's streams. + */ + void set_group_memory(GroupId group, std::vector descriptors); + + /** + * @brief Serve readers. After a stop() this takes the path again. + * @throws std::system_error if another process took the path meanwhile. + */ + void start(); + + /** + * @brief Stop serving: every subscription ends, every reader sees its connection close, and + * the path is given up, so a reader that tries to connect is refused at once. Does nothing + * if the endpoint is not serving. + */ + void stop(); + + // Readers connected right now. + std::size_t reader_count() const; + +private: + class Impl; + std::unique_ptr m_impl; +}; + +} // namespace core::camera diff --git a/tests/cpp/core/CMakeLists.txt b/tests/cpp/core/CMakeLists.txt index 35bbcad055..803dfcffbf 100644 --- a/tests/cpp/core/CMakeLists.txt +++ b/tests/cpp/core/CMakeLists.txt @@ -18,6 +18,7 @@ add_subdirectory(camera_core) if(CMAKE_SYSTEM_NAME STREQUAL "Linux") add_subdirectory(camera_ipc) add_subdirectory(camera_wire) + add_subdirectory(camera_endpoint) endif() if(BUILD_OVXR_CAMERA_QUADS) diff --git a/tests/cpp/core/camera_endpoint/CMakeLists.txt b/tests/cpp/core/camera_endpoint/CMakeLists.txt new file mode 100644 index 0000000000..5a8373c671 --- /dev/null +++ b/tests/cpp/core/camera_endpoint/CMakeLists.txt @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +find_package(Threads REQUIRED) + +add_executable(camera_endpoint_tests + test_endpoint.cpp +) + +# The tests play the reader's part with the socket and the codec themselves. +target_link_libraries(camera_endpoint_tests PRIVATE + camera::camera_endpoint + camera::camera_ipc + camera::camera_wire + Catch2::Catch2WithMain + Threads::Threads +) + +message(STATUS "camera_endpoint_tests target enabled with Catch2") +catch_discover_tests(camera_endpoint_tests ADD_TAGS_AS_LABELS) diff --git a/tests/cpp/core/camera_endpoint/test_endpoint.cpp b/tests/cpp/core/camera_endpoint/test_endpoint.cpp new file mode 100644 index 0000000000..d99eba0ad5 --- /dev/null +++ b/tests/cpp/core/camera_endpoint/test_endpoint.cpp @@ -0,0 +1,419 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace core::camera; +using namespace std::chrono_literals; +using Catch::Matchers::ContainsSubstring; + +namespace +{ + +constexpr std::uint32_t WIDTH = 64; +constexpr std::uint32_t HEIGHT = 48; +constexpr std::uint32_t SLOTS = 8; + +class TemporaryDirectory +{ +public: + TemporaryDirectory() + { + std::string pattern = (std::filesystem::temp_directory_path() / "camera_endpoint_XXXXXX").string(); + REQUIRE(::mkdtemp(pattern.data()) != nullptr); + m_path = pattern; + } + + ~TemporaryDirectory() + { + std::error_code ignored; + std::filesystem::remove_all(m_path, ignored); + } + + std::string socket_path() const + { + return (m_path / "cameras.sock").string(); + } + +private: + std::filesystem::path m_path; +}; + +GroupDescription gray_group(const std::string& id, std::size_t streams) +{ + GroupDescription group; + group.id = id; + for (std::size_t i = 0; i < streams; ++i) + { + StreamDescription stream; + stream.id = id + "/" + std::to_string(i); + stream.pixel_format = PixelFormat::GRAY8; + stream.width = WIDTH; + stream.height = HEIGHT; + stream.plane_count = 1; + stream.planes[0].stride_bytes = WIDTH; + stream.slot_bytes = WIDTH * HEIGHT; + stream.slot_count = SLOTS; + stream.frame_rate = 60.0; + group.streams.push_back(stream); + } + return group; +} + +// A plugin in miniature: a stereo group and a single camera, in host memory, behind an endpoint. +struct Served +{ + TemporaryDirectory directory; + Publisher publisher; + GroupId head = publisher.add_group(gray_group("head", 2)); + GroupId wrist = publisher.add_group(gray_group("wrist", 1)); + HostPool left{ SLOTS, WIDTH* HEIGHT, "test_left" }; + HostPool right{ SLOTS, WIDTH* HEIGHT, "test_right" }; + HostPool hand{ SLOTS, WIDTH* HEIGHT, "test_wrist" }; + Endpoint endpoint{ publisher, directory.socket_path() }; + + Served() + { + endpoint.set_group_memory(head, { left.descriptor(), right.descriptor() }); + endpoint.set_group_memory(wrist, { hand.descriptor() }); + endpoint.start(); + } + + // Publishes one stereo frame set whose every pixel is `value`. + std::uint64_t publish(std::uint8_t value) + { + std::vector images(2); + HostPool* pools[] = { &left, &right }; + for (std::size_t i = 0; i < 2; ++i) + { + const auto slot = publisher.acquire_slot(head, i); + REQUIRE(slot.has_value()); + std::fill(pools[i]->slot(*slot).begin(), pools[i]->slot(*slot).end(), std::byte{ value }); + images[i].slot = *slot; + } + return publisher.publish(head, images, {}); + } +}; + +// The reader's part, played with the socket and the codec directly. +struct Reader +{ + struct Received + { + ReceiveStatus status = ReceiveStatus::TIMEOUT; + WireMessage message; + std::vector descriptors; + }; + + explicit Reader(const Served& served) : socket(MessageSocket::connect(served.directory.socket_path())) + { + } + + template + void send(const Message& message) + { + REQUIRE(socket.send(encoder.encode(message)) == SendStatus::SENT); + } + + Received receive(std::chrono::milliseconds timeout = 2s) + { + Received result; + ReceivedMessage received = socket.receive(buffer, timeout); + result.status = received.status; + if (received.status == ReceiveStatus::MESSAGE) + { + result.message = decode_wire_message({ buffer.data(), received.bytes }); + result.descriptors = std::move(received.descriptors); + } + return result; + } + + template + Message expect(std::chrono::milliseconds timeout = 2s) + { + Received received = receive(timeout); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(std::holds_alternative(received.message)); + return std::get(std::move(received.message)); + } + + WelcomeMessage hello(const std::string& name = "test reader") + { + send(HelloMessage{ .reader_name = name }); + return expect(); + } + + // Subscribes and returns the answer with the pool descriptors that came with it. + std::pair> subscribe(const std::string& group, ReaderOptions options = {}) + { + send(SubscribeMessage{ group, options }); + Received received = receive(); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + REQUIRE(std::holds_alternative(received.message)); + return { std::get(std::move(received.message)), std::move(received.descriptors) }; + } + + MessageSocket socket; + WireEncoder encoder; + std::vector buffer = std::vector(MAX_WIRE_MESSAGE_BYTES); +}; + +bool wait_until(const std::function& condition, std::chrono::milliseconds timeout = 2s) +{ + const auto deadline = std::chrono::steady_clock::now() + timeout; + while (!condition()) + { + if (std::chrono::steady_clock::now() > deadline) + { + return false; + } + std::this_thread::sleep_for(1ms); + } + return true; +} + +} // namespace + +TEST_CASE("a reader is told what is published", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + + const WelcomeMessage welcome = reader.hello(); + REQUIRE(welcome.error.empty()); + REQUIRE(welcome.protocol_version == WIRE_PROTOCOL_VERSION); + REQUIRE(welcome.groups.size() == 2); + REQUIRE(welcome.groups[0].id == "head"); + REQUIRE(welcome.groups[0].streams.size() == 2); + REQUIRE(welcome.groups[0].streams[1].id == "head/1"); + REQUIRE(welcome.groups[0].streams[1].width == WIDTH); + REQUIRE(welcome.groups[1].id == "wrist"); + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 1; })); +} + +TEST_CASE("a reader that speaks another protocol version is refused", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + + reader.send(HelloMessage{ .protocol_version = WIRE_PROTOCOL_VERSION + 1, .reader_name = "from the future" }); + const WelcomeMessage welcome = reader.expect(); + REQUIRE_THAT(welcome.error, ContainsSubstring("protocol version")); + REQUIRE(welcome.groups.empty()); + REQUIRE(reader.receive().status == ReceiveStatus::CLOSED); +} + +TEST_CASE("a subscriber maps the pools and is sent frame sets", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + + auto [subscribed, descriptors] = reader.subscribe("head"); + REQUIRE(subscribed.error.empty()); + REQUIRE(subscribed.group.id == "head"); + REQUIRE(descriptors.size() == 2); + const HostPoolView left(std::move(descriptors[0]), SLOTS, WIDTH * HEIGHT); + const HostPoolView right(std::move(descriptors[1]), SLOTS, WIDTH * HEIGHT); + + served.publish(0x11); + const FrameEvent first = reader.expect(); + REQUIRE(first.sequence == 1); + REQUIRE(first.image_count == 2); + REQUIRE(first.skipped == 0); + REQUIRE(first.timeline.published_ns != TIME_UNKNOWN); + REQUIRE(first.timeline.sent_ns >= first.timeline.published_ns); + REQUIRE(left.slot(first.images[0].slot).front() == std::byte{ 0x11 }); + REQUIRE(right.slot(first.images[1].slot).back() == std::byte{ 0x11 }); + + // A window of one holds one frame set; the next comes with the release, and is the newest. + served.publish(0x22); + served.publish(0x33); + REQUIRE(reader.receive(20ms).status == ReceiveStatus::TIMEOUT); + REQUIRE(left.slot(first.images[0].slot).front() == std::byte{ 0x11 }); // still held, so not rewritten + + reader.send(ReleaseMessage{ first.lease_id }); + const FrameEvent newest = reader.expect(); + REQUIRE(newest.sequence == 3); + REQUIRE(newest.skipped == 1); + REQUIRE(left.slot(newest.images[0].slot).front() == std::byte{ 0x33 }); +} + +TEST_CASE("a subscription that cannot be served is refused and the connection stays usable", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + + auto [unknown, no_descriptors] = reader.subscribe("chest"); + REQUIRE_THAT(unknown.error, ContainsSubstring("no group 'chest'")); + REQUIRE(no_descriptors.empty()); + + auto [too_large, none] = reader.subscribe("head", { .window = SLOTS }); + REQUIRE_THAT(too_large.error, ContainsSubstring("does not fit the pool")); + REQUIRE(none.empty()); + + auto [accepted, descriptors] = reader.subscribe("wrist"); + REQUIRE(accepted.error.empty()); + REQUIRE(descriptors.size() == 1); + + auto [second, extra] = reader.subscribe("head"); + REQUIRE_THAT(second.error, ContainsSubstring("one subscription")); + REQUIRE(extra.empty()); +} + +TEST_CASE("a reader that disappears returns what it held", "[unit][camera_endpoint]") +{ + Served served; + { + Reader reader(served); + reader.hello(); + auto [subscribed, descriptors] = reader.subscribe("head", { .window = 2, .order = DeliveryOrder::IN_ORDER }); + REQUIRE(subscribed.error.empty()); + served.publish(1); + served.publish(2); + REQUIRE(reader.expect().sequence == 1); + REQUIRE(reader.expect().sequence == 2); + REQUIRE(served.endpoint.reader_count() == 1); + // Gone without releasing either frame set. + } + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 0; })); + + // With the held slots back, capture runs through the whole pool again and again. + for (std::uint8_t i = 0; i < 3 * SLOTS; ++i) + { + served.publish(i); + } + REQUIRE(served.publisher.stats(served.head).no_free_slot == 0); + + // And the room in the pool is there for the next reader. + Reader next(served); + next.hello(); + auto [again, descriptors] = next.subscribe("head", { .window = 2, .order = DeliveryOrder::IN_ORDER }); + REQUIRE(again.error.empty()); +} + +TEST_CASE("a reader that breaks the protocol is dropped and the others are not", "[unit][camera_endpoint]") +{ + Served served; + Reader good(served); + good.hello(); + auto [subscribed, descriptors] = good.subscribe("head"); + REQUIRE(subscribed.error.empty()); + + Reader garbage(served); + const std::vector noise(32, std::byte{ 0x5a }); + REQUIRE(garbage.socket.send(noise) == SendStatus::SENT); + REQUIRE(garbage.receive().status == ReceiveStatus::CLOSED); + + Reader impostor(served); + impostor.hello(); + impostor.send(WelcomeMessage{}); + REQUIRE(impostor.receive().status == ReceiveStatus::CLOSED); + + Reader impatient(served); + impatient.send(SubscribeMessage{ "head", {} }); + REQUIRE(impatient.receive().status == ReceiveStatus::CLOSED); + + REQUIRE(wait_until([&] { return served.endpoint.reader_count() == 1; })); + served.publish(7); + REQUIRE(good.expect().sequence == 1); +} + +TEST_CASE("readers do not slow each other", "[unit][camera_endpoint]") +{ + Served served; + Reader stalled(served); + stalled.hello(); + REQUIRE(stalled.subscribe("head").first.error.empty()); + Reader live(served); + live.hello(); + REQUIRE(live.subscribe("head").first.error.empty()); + + // One reader never releases; the other still gets every frame set. + for (std::uint64_t sequence = 1; sequence <= 5; ++sequence) + { + REQUIRE(served.publish(static_cast(sequence)) == sequence); + const FrameEvent event = live.expect(); + REQUIRE(event.sequence == sequence); + REQUIRE(event.skipped == 0); + // Whether the release is seen before or after the next publish, that frame set is next. + live.send(ReleaseMessage{ event.lease_id }); + } + REQUIRE(stalled.expect().sequence == 1); + REQUIRE(stalled.receive(20ms).status == ReceiveStatus::TIMEOUT); +} + +TEST_CASE("stopping the endpoint closes every reader, and it can serve again", "[unit][camera_endpoint]") +{ + Served served; + Reader reader(served); + reader.hello(); + REQUIRE(reader.subscribe("head").first.error.empty()); + + served.endpoint.stop(); + REQUIRE(reader.receive().status == ReceiveStatus::CLOSED); + REQUIRE(served.endpoint.reader_count() == 0); + served.endpoint.stop(); // nothing to stop + + // A stopped endpoint refuses a reader at once; it does not leave it waiting for an answer. + REQUIRE_THROWS_AS(MessageSocket::connect(served.directory.socket_path()), std::system_error); + + served.endpoint.start(); + Reader next(served); + REQUIRE(next.hello().groups.size() == 2); + REQUIRE(next.subscribe("head").first.error.empty()); + served.publish(9); + REQUIRE(next.expect().sequence == 1); +} + +TEST_CASE("a group needs its memory named before readers can subscribe", "[unit][camera_endpoint]") +{ + TemporaryDirectory directory; + Publisher publisher; + const GroupId head = publisher.add_group(gray_group("head", 2)); + HostPool pool(SLOTS, WIDTH * HEIGHT, "test"); + Endpoint endpoint(publisher, directory.socket_path()); + + REQUIRE_THROWS_AS(endpoint.set_group_memory(head, { pool.descriptor() }), std::invalid_argument); + REQUIRE_THROWS_AS(endpoint.set_group_memory(head + 1, {}), std::out_of_range); + endpoint.start(); + REQUIRE_THROWS_AS(endpoint.set_group_memory(head, { pool.descriptor(), pool.descriptor() }), std::logic_error); + + MessageSocket socket = MessageSocket::connect(directory.socket_path()); + WireEncoder encoder; + std::vector buffer(MAX_WIRE_MESSAGE_BYTES); + REQUIRE(socket.send(encoder.encode(HelloMessage{})) == SendStatus::SENT); + REQUIRE(socket.receive(buffer, 2s).status == ReceiveStatus::MESSAGE); + REQUIRE(socket.send(encoder.encode(SubscribeMessage{ "head", {} })) == SendStatus::SENT); + const ReceivedMessage received = socket.receive(buffer, 2s); + REQUIRE(received.status == ReceiveStatus::MESSAGE); + const WireMessage answer = decode_wire_message({ buffer.data(), received.bytes }); + REQUIRE_THAT(std::get(answer).error, ContainsSubstring("no memory a reader can map")); + + // Another endpoint cannot take the same path while this one lives. + REQUIRE_THROWS_AS(Endpoint(publisher, directory.socket_path()), std::system_error); +}