Clarify publisher stats API

Author: mondain

docs/publisher-api.md

@@ -209,25 +209,36 @@ For service-style integration:
 5. For continuous input, run `publish_live(...)` in a worker thread.
 6. Use `TransportStatus` messages for metrics and retry decisions.
 
-## 11. Runtime Stats (`stats_json`)
+## 11. Publish Summary (`stats`)
 
-You can query publisher runtime state at any time:
+The publisher API is blocking: `publish(...)`, `publish_file(...)`,
+`publish_stream(...)`, and `publish_live(...)` run the session on the calling
+thread. Because there is no built-in polling loop, stats are exposed as a
+structured summary of the current or most recent publish operation rather than
+as a live telemetry stream.
 
 ```cpp
-const std::string stats = publisher.stats_json();
-std::cout << stats << "\n";
+const auto stats = publisher.stats();
+std::cout << "bytes=" << stats.bytes_published
+          << " objects=" << stats.objects_published
+          << " groups=" << stats.groups_published << "\n";
 ```
 
-Current JSON fields:
+Current fields:
 
-- `active`: whether a session is currently active
-- `connected`: whether transport is currently connected
 - `publishingLive`: whether the active session is live-publish mode
 - `bytesPublished`: total payload bytes published in the current/last session
 - `objectsPublished`: total objects published in the current/last session
 - `groupsPublished`: total (track, group) units published in the current/last session
 - `splitCmafChunks`: current packaging mode (`true` = split chunks, `false` = coalesced chunks)
 - `includeSap`: whether SAP track/object packaging is enabled
+- `transport`, `host`, `port`, `path`: endpoint context for the current/last session
+- `connectionId`: last known transport connection ID
+- `lastError`: last publisher-level error, if any
+
+`stats_json()` remains available for existing integrations, but it is deprecated
+because a JSON polling API implies runtime telemetry support that the blocking
+publisher API does not provide.
 - `transport`: `"raw_quic"` or `"webtransport"`
 - `host`: configured endpoint host
 - `port`: configured endpoint port

examples/psychedelic/Psychedelic.cpp

@@ -221,8 +221,11 @@ int main(int argc, char** argv) {
             throw std::runtime_error("disconnect failed: " + disconnect_status.message);
         }
 
+        const auto stats = publisher.stats();
         std::cout << "[psychedelic] done (single namespace, separate A/V tracks)\n";
-        std::cout << "[psychedelic] stats: " << publisher.stats_json() << '\n';
+        std::cout << "[psychedelic] published bytes=" << stats.bytes_published
+                  << " objects=" << stats.objects_published
+                  << " groups=" << stats.groups_published << '\n';
         return 0;
     } catch (const std::exception& error) {
         std::cerr << "error: " << error.what() << '\n';

examples/psychedelic/README.md

@@ -9,7 +9,7 @@ It now:
 - publishes via one `Publisher::publish_live(...)` session
 - uses one namespace containing separate video/audio tracks
 - performs explicit graceful teardown with `disconnect(0)`
-- prints `stats_json()`
+- prints the structured post-publish `Publisher::stats()` summary
 
 ## Prerequisites
 

include/openmoq/publisher/publisher_api.h

@@ -35,6 +35,21 @@ struct PreparedPublish {
     PublishPlan plan;
 };
 
+struct PublisherStats {
+    bool publishing_live = false;
+    std::uint64_t bytes_published = 0;
+    std::uint64_t objects_published = 0;
+    std::uint64_t groups_published = 0;
+    bool split_cmaf_chunks = true;
+    bool include_sap = false;
+    transport::TransportKind transport = transport::TransportKind::kRawQuic;
+    std::string host;
+    std::uint16_t port = 0;
+    std::string path;
+    std::string connection_id;
+    std::string last_error;
+};
+
 class Publisher {
 public:
     using TransportFactory = std::function<std::unique_ptr<transport::PublisherTransport>(transport::TransportKind)>;
@@ -68,6 +83,8 @@ class Publisher {
                                             const transport::TlsConfig& tls = {},
                                             bool endpoint_alpn_overridden = false) const;
     transport::TransportStatus disconnect(std::uint64_t application_error_code = 0) const;
+    PublisherStats stats() const;
+    [[deprecated("Use stats(); live polling is not supported by the blocking publish API.")]]
     std::string stats_json() const;
 
 private:

src/publisher_api.cpp

@@ -261,6 +261,36 @@ transport::TransportStatus Publisher::disconnect(std::uint64_t application_error
     return status;
 }
 
+PublisherStats Publisher::stats() const {
+    StatsSnapshot snapshot;
+    bool split_cmaf_chunks = true;
+    bool include_sap = false;
+    {
+        std::lock_guard<std::mutex> lock(state_mutex_);
+        snapshot = stats_;
+        split_cmaf_chunks = config_.split_cmaf_chunks;
+        include_sap = config_.include_sap;
+        if (active_session_ && active_session_->transport) {
+            snapshot.connection_id = active_session_->transport->connection_id();
+        }
+    }
+
+    return PublisherStats{
+        .publishing_live = snapshot.publishing_live,
+        .bytes_published = snapshot.bytes_published,
+        .objects_published = snapshot.objects_published,
+        .groups_published = snapshot.groups_published,
+        .split_cmaf_chunks = split_cmaf_chunks,
+        .include_sap = include_sap,
+        .transport = snapshot.transport,
+        .host = snapshot.host,
+        .port = snapshot.port,
+        .path = snapshot.path,
+        .connection_id = snapshot.connection_id,
+        .last_error = snapshot.last_error,
+    };
+}
+
 std::string Publisher::stats_json() const {
     StatsSnapshot snapshot;
     bool split_cmaf_chunks = true;