feat(hermes): Implement IPFS publishing workflow (#694)

* feat: implement doc-sync channel::post API for issue #628

- Add channel::post(document_bytes) API as requested
- Integrate hermes-ipfs library for IPFS operations
- Add HTTP endpoints for testing (/api/doc-sync/*)
- Configure HTTP gateway routing
- Implement IPFS add, pin, and PubSub publish workflow

* feat: implement doc-sync channel::post API for issue #628

- Add channel::post(document_bytes) API as requested
- Integrate hermes-ipfs library for IPFS operations
- Add HTTP endpoints for testing (/api/doc-sync/*)
- Configure HTTP gateway routing
- Implement IPFS add, pin, and PubSub publish workflow

* hermes ipfs version

* fix: enable WASM compilation for doc-sync module and add host stubs

  WASM compilation fixes:
  - Made tokio runtime features conditional (rt-multi-thread only for non-WASM)
  - Added separate WASM/native implementations using futures::executor for WASM
  - Conditionally compile Runtime usage and block_on calls

  Host implementation:
  - Replaced panicking todo!() with warning messages and stub return values
  - Added Resource stub creation for SyncChannel::new()
  - Functions now print warnings but don't crash runtime

  This allows the doc-sync module to compile for wasm32-wasip2 targets and
  run without panicking, though full functionality requires proper host
  implementation.

* Remove all cfg attributes and consolidate WASM/non-WASM code paths into single implementations using futures::executor. Simplify HTTP handlers and reduce complexity to clearly
   demonstrate the 4-step workflow.

* refactor(doc-sync): simplify for demo workflow

   Remove conditional compilation, OnceLock pattern, and unnecessary complexity to clearly show the 4-step IPFS PubSub workflow.

* refactor(doc-sync): use WIT bindings directly for demo

  Replace async hermes-ipfs library with direct WIT function calls (file_add, file_pin, pubsub_publish). Remove conditional compilation and async dependencies to simplify the 4-step
  workflow demo.

* refactor(doc-sync): use WIT bindings directly for demo

  Replace async hermes-ipfs library with direct WIT function calls (file_add, file_pin, pubsub_publish). Remove conditional compilation and async dependencies to simplify the 4-step
  workflow demo.

* refactor(doc-sync): integrate with PR #691 subscription flow

  Replace async hermes-ipfs library with synchronous WIT bindings (file_add, file_pin, pubsub_publish, pubsub_subscribe). Add actual channel subscription in SyncChannel::new() and
  document complete pub/sub flow with PR #691 infrastructure.

  Changes:
  - Use WIT IPFS functions directly instead of async library
  - Call pubsub_subscribe() to register DocSync subscriptions
  - Document how on_new_doc events are triggered by PR #691
  - Remove conditional compilation and async dependencies
  - Show clear 4-step workflow: add → pin → validate → publish

* docs(doc-sync): document PR #691 integration requirements

  Add comprehensive comments explaining PR #691 requirement for subscription event routing. Document the complete pub/sub flow, what works now vs what needs PR #691, and how to
  integrate when it merges

* fix(doc-sync): import GuestSyncChannel trait and clarify PR #691 comment

  Fix compilation error and clarify that publishing to PubSub works now; PR #691 is only needed to route incoming messages to event handlers.

* update docs

* refactor(doc-sync): Focus module on publishing workflow only

  Remove subscription logic and simplify documentation. Module now
  demonstrates only the 4-step publishing workflow: file_add, file_pin,
  pre-publish validation, and pubsub_publish.

* fmt

* refactor(doc-sync): Move post logic to host

  Execute the 4-step publishing workflow (file_add, file_pin, pre-publish,
  pubsub_publish) on the host side instead of in the WASM module. Reduces
  boundary crossings from 6 to 2 for better performance.

* fmt

* fmt

* fix(doc-sync): Fix compilation errors

  - Fix SyncChannel resource import and usage
  - Update channel::post() to call host implementation correctly

* refactor(doc-sync): Replace eprintln with tracing

  Use tracing macros (info/warn/error) instead of eprintln for logging
  in doc-sync host implementation.

* refactor(doc-sync): Replace eprintln with tracing

  Use tracing macros (info/warn/error) instead of eprintln for logging
  in doc-sync host implementation.

* fmt

* refactor(doc-sync): Extract constants and improve error logging

  - Add DOC_SYNC_TOPIC and DOC_SYNC_CHANNEL constants
  - Add error logging to id_for() method

* refactor(doc-sync): Improve error logging and remove redundant conversions

  - Log actual error details instead of discarding with
  - Remove redundant .to_string() on CID response
  - Add error logging for failed post operations

* fmt

Author: cong-or

hermes/Cargo.lock

@@ -27,7 +27,11 @@
 		{
 			"package": "modules/auth/lib/auth.hmod",
 			"name": "auth"
+		},
+		{
+			"package": "modules/doc-sync/lib/doc_sync.hmod",
+			"name": "doc_sync"
 		}
 	],
 	"www": "modules/http-proxy/lib/www"
-}
+}

hermes/apps/athena/Cargo.lock

@@ -12,3 +12,4 @@ crate-type = ["cdylib"]
 
 [dependencies]
 shared = { version = "0.1.0", path = "../../shared" }
+serde_json = "1.0.145"

hermes/apps/athena/manifest_app.json

@@ -0,0 +1,33 @@
+# Doc Sync Module
+
+Thin wrapper for posting documents to IPFS PubSub.
+The actual 4-step workflow (file_add, file_pin, pre-publish, pubsub_publish) is executed on the host side for efficiency.
+
+## Usage
+
+```rust
+use doc_sync::channel;
+
+let cid = channel::post(document_bytes)?;
+```
+
+## Architecture
+
+The doc-sync module provides a simple API for publishing documents to IPFS via PubSub channels.
+All heavy operations are delegated to the host-side implementation for performance:
+
+1. **file_add** - Add document to IPFS
+2. **file_pin** - Pin the document
+3. **pre-publish** - Prepare for PubSub
+4. **pubsub_publish** - Publish to the channel
+
+## HTTP Gateway
+
+The module exposes an HTTP endpoint for testing:
+
+```bash
+curl -X POST http://localhost:5000/api/doc-sync/post \
+  -H "Host: athena.hermes.local" \
+  -H "Content-Type: text/plain" \
+  -d "Hello, IPFS!"
+```

hermes/apps/athena/modules/doc-sync/Cargo.toml

@@ -1,5 +1,5 @@
 #![allow(missing_docs)]
-//! Doc Sync Module
+//! Doc Sync - IPFS `PubSub` document publishing. See README.md for details.
 
 shared::bindings_generate!({
     world: "hermes:app/hermes",
@@ -11,40 +11,136 @@ shared::bindings_generate!({
             include wasi:cli/imports@0.2.6;
             import hermes:doc-sync/api;
             import hermes:logging/api;
+            import hermes:http-gateway/api;
 
             export hermes:init/event;
             export hermes:doc-sync/event;
+            export hermes:http-gateway/event;
         }
     ",
-    share: ["hermes:logging", "hermes:doc-sync"],
+    share: ["hermes:logging"],
 });
 
 export!(Component);
 
+use hermes::{
+    doc_sync::api::{DocData, SyncChannel},
+    http_gateway::api::{Bstr, Headers, HttpGatewayResponse, HttpResponse},
+};
 use shared::{
-    bindings::hermes::doc_sync::api::{ChannelName, DocData, SyncChannel},
-    utils::log::{self, info, warn},
+    bindings::hermes::doc_sync::api::ChannelName,
+    utils::log::{self, error, info},
 };
 
-/// Doc Sync component.
+/// Doc Sync component - thin wrapper calling host-side implementation.
 struct Component;
 
 impl exports::hermes::init::event::Guest for Component {
+    /// Initialize the module.
     fn init() -> bool {
         log::init(log::LevelFilter::Trace);
-        info!(target: "doc_sync::init", "💫 Opening channel...");
-        let _chan = SyncChannel::new("documents");
-        info!(target: "doc_sync::init", "💫 Channel opened");
+        info!(target: "doc_sync::init", "Doc sync module initialized");
         true
     }
 }
 
+/// Stub event handler for receiving documents (not used in this publishing-only demo).
 impl exports::hermes::doc_sync::event::Guest for Component {
     fn on_new_doc(
-        channel: ChannelName,
-        doc: DocData,
+        _channel: ChannelName,
+        _doc: DocData,
     ) {
+        // Not implemented - this demo only shows publishing
+    }
+}
+
+/// HTTP Gateway endpoint for testing with curl.
+///
+/// POST /api/doc-sync/post - Post a document to the "documents" channel
+///
+/// Example:
+/// ```bash
+/// curl -X POST http://localhost:5000/api/doc-sync/post \
+///   -H "Host: athena.hermes.local" \
+///   -H "Content-Type: text/plain" \
+///   -d "Hello, IPFS!"
+/// ```
+impl exports::hermes::http_gateway::event::Guest for Component {
+    fn reply(
+        body: Vec<u8>,
+        _headers: Headers,
+        path: String,
+        method: String,
+    ) -> Option<HttpGatewayResponse> {
         log::init(log::LevelFilter::Trace);
-        warn!(target: "doc_sync::on_new_doc", channel:%, doc_byte_length = doc.len(); "Unimplemented!");
+        info!(target: "doc_sync", "HTTP {method} {path}");
+
+        match (method.as_str(), path.as_str()) {
+            ("POST", "/api/doc-sync/post") => {
+                // Call channel::post (executes 4-step workflow on host)
+                match channel::post(&body) {
+                    Ok(cid_bytes) => {
+                        let cid = String::from_utf8_lossy(&cid_bytes);
+                        Some(json_response(
+                            200,
+                            &serde_json::json!({
+                                "success": true,
+                                "cid": cid
+                            }),
+                        ))
+                    },
+                    Err(e) => {
+                        error!(target: "doc_sync", "Failed to post document: {e:?}");
+                        Some(json_response(
+                            500,
+                            &serde_json::json!({
+                                "success": false,
+                                "error": "Failed to post document"
+                            }),
+                        ))
+                    },
+                }
+            },
+            _ => {
+                Some(json_response(
+                    404,
+                    &serde_json::json!({"error": "Not found"}),
+                ))
+            },
+        }
+    }
+}
+
+/// Helper to create JSON HTTP responses.
+fn json_response(
+    code: u16,
+    body: &serde_json::Value,
+) -> HttpGatewayResponse {
+    HttpGatewayResponse::Http(HttpResponse {
+        code,
+        headers: vec![("content-type".to_string(), vec![
+            "application/json".to_string(),
+        ])],
+        body: Bstr::from(body.to_string()),
+    })
+}
+
+/// Default channel name for doc-sync operations
+const DOC_SYNC_CHANNEL: &str = "documents";
+
+/// API for posting documents to IPFS `PubSub` channels.
+pub mod channel {
+    use super::{DOC_SYNC_CHANNEL, DocData, SyncChannel, hermes};
+
+    /// Post a document to the "documents" channel. Returns the document's CID.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the document cannot be posted to the channel.
+    pub fn post(document_bytes: &DocData) -> Result<Vec<u8>, hermes::doc_sync::api::Errno> {
+        // Create channel via host
+        let channel = SyncChannel::new(DOC_SYNC_CHANNEL);
+        // Post document via host (executes 4-step workflow in host)
+        channel.post(document_bytes)
     }
 }

hermes/apps/athena/modules/doc-sync/README.md

@@ -60,7 +60,6 @@ pub fn bootstrap(
     let ipfs_node = HermesIpfsNode::init(
         HermesIpfsBuilder::new()
             .with_default()
-            .set_default_listener()
             .set_disk_storage(ipfs_data_path.clone()),
         default_bootstrap,
     )?;
@@ -109,6 +108,11 @@ where N: hermes_ipfs::rust_ipfs::NetworkBehaviour<ToSwarm = Infallible> + Send +
                     );
                 }
                 let hermes_node: HermesIpfs = node.into();
+                // Enable DHT server mode for PubSub support
+                hermes_node
+                    .dht_mode(hermes_ipfs::rust_ipfs::DhtMode::Server)
+                    .await?;
+                tracing::debug!("IPFS node set to DHT server mode");
                 let h = tokio::spawn(ipfs_command_handler(hermes_node, receiver));
                 let (..) = tokio::join!(h);
                 Ok::<(), anyhow::Error>(())

hermes/apps/athena/modules/doc-sync/src/lib.rs

@@ -97,11 +97,14 @@ pub(crate) async fn ipfs_command_handler(
                 send_response(Ok(response), tx);
             },
             IpfsCommand::Publish(topic, message, tx) => {
-                hermes_node
-                    .pubsub_publish(topic, message)
+                let result = hermes_node
+                    .pubsub_publish(&topic, message)
                     .await
-                    .map_err(|_| Errno::PubsubPublishError)?;
-                send_response(Ok(()), tx);
+                    .map_err(|e| {
+                        tracing::error!(topic = %topic, "pubsub_publish failed: {}", e);
+                        Errno::PubsubPublishError
+                    });
+                send_response(result, tx);
             },
             IpfsCommand::Subscribe(topic, tx) => {
                 let stream = hermes_node

hermes/bin/src/ipfs/mod.rs

@@ -167,7 +167,7 @@ pub(crate) fn init(logger_config: &LoggerConfig) -> anyhow::Result<()> {
         .with_timer(time::UtcTime::rfc_3339())
         .with_span_events(FmtSpan::CLOSE)
         .with_max_level(LevelFilter::from_level(logger_config.log_level.into()))
-        // Hardcode the filter to always suppress IPFS noise
+        // Hardcode the filter to always suppress excess noise
         .with_env_filter(EnvFilter::new("hermes=info,rust_ipfs=error"))
         .finish();