feat(trogon-sink-github): add webhook receiver that sinks events to NATS JetStream

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

devops/docker/compose/GITHUB_WEBHOOKS.md

@@ -0,0 +1,65 @@
+# Receiving GitHub Webhooks Locally
+
+## Prerequisites
+
+- Docker Compose
+- A GitHub App (org or personal) — the app's webhook delivers events from every
+  repo where it's installed, so you configure the URL once
+
+## 1. Generate a webhook secret
+
+```bash
+openssl rand -hex 32
+```
+
+Save the output — you'll use it in both GitHub and the local stack.
+
+## 2. Create a smee.io channel
+
+Go to [smee.io](https://smee.io) and click **Start a new channel**. Copy the
+channel URL (e.g. `https://smee.io/abc123`).
+
+## 3. Configure your GitHub App
+
+1. Go to **Settings → Developer settings → GitHub Apps**
+2. Select your app (or create a new one)
+3. Under **Webhook**:
+   - **Webhook URL**: your smee.io channel URL
+   - **Webhook secret**: the secret you generated in step 1
+4. Under **Permissions & events**, subscribe to the events you need
+5. Install the app on the repositories or organization you want to receive
+   events from
+
+## 4. Start the stack
+
+```bash
+SMEE_URL=https://smee.io/abc123 \
+GITHUB_WEBHOOK_SECRET=<secret-from-step-1> \
+docker compose --profile dev up
+```
+
+This starts NATS, the webhook receiver, and the smee client. The smee client
+connects to your channel and forwards events to the webhook receiver.
+
+Without `--profile dev`, the smee client is excluded and only the core services
+start.
+
+## 5. Verify
+
+Trigger an event in a repository where the app is installed (e.g. push a
+commit). You should see:
+
+- The event appear on your smee.io channel page
+- The smee client forward it to the webhook receiver
+- The webhook receiver publish it to NATS on `github.{event}`
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `GITHUB_WEBHOOK_SECRET` | yes | — | HMAC-SHA256 secret (must match GitHub App) |
+| `SMEE_URL` | yes (dev profile) | — | smee.io channel URL |
+| `GITHUB_WEBHOOK_PORT` | no | `8080` | HTTP port for the webhook receiver |
+| `GITHUB_SUBJECT_PREFIX` | no | `github` | NATS subject prefix |
+| `GITHUB_STREAM_NAME` | no | `GITHUB` | JetStream stream name |
+| `RUST_LOG` | no | `info` | Log level |

devops/docker/compose/compose.yml

@@ -2,13 +2,66 @@ name: trogonai
 
 services:
   nats:
-    image: nats:latest
-    container_name: nats
-    command: 
+    image: nats:alpine
+    command:
       - "--jetstream"
       - "--store_dir=/data"
+      - "--http_port=8222"
+    ports:
+      - "4222:4222"
+      - "8222:8222"
     volumes:
       - nats_data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8222/healthz"]
+      interval: 5s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
+
+  trogon-sink-github:
+    build:
+      context: ../../../rsworkspace
+      dockerfile: crates/trogon-sink-github/Dockerfile
+    ports:
+      - "${GITHUB_WEBHOOK_PORT:-8080}:${GITHUB_WEBHOOK_PORT:-8080}"
+    environment:
+      NATS_URL: "nats:4222"
+      GITHUB_WEBHOOK_SECRET: "${GITHUB_WEBHOOK_SECRET:?GITHUB_WEBHOOK_SECRET is required}"
+      GITHUB_WEBHOOK_PORT: "${GITHUB_WEBHOOK_PORT:-8080}"
+      GITHUB_SUBJECT_PREFIX: "${GITHUB_SUBJECT_PREFIX:-github}"
+      GITHUB_STREAM_NAME: "${GITHUB_STREAM_NAME:-GITHUB}"
+      GITHUB_STREAM_MAX_AGE_SECS: "${GITHUB_STREAM_MAX_AGE_SECS:-604800}"
+      GITHUB_NATS_ACK_TIMEOUT_SECS: "${GITHUB_NATS_ACK_TIMEOUT_SECS:-10}"
+      GITHUB_MAX_BODY_SIZE: "${GITHUB_MAX_BODY_SIZE:-26214400}"
+      RUST_LOG: "${RUST_LOG:-info}"
+    depends_on:
+      nats:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:${GITHUB_WEBHOOK_PORT:-8080}/health"]
+      interval: 10s
+      timeout: 3s
+      start_period: 10s
+      retries: 3
+
+  smee:
+    image: node:alpine
+    command:
+      - npx
+      - smee-client
+      - --url
+      - "${SMEE_URL:?SMEE_URL is required — create a channel at https://smee.io}"
+      - --target
+      - "http://trogon-sink-github:${GITHUB_WEBHOOK_PORT:-8080}/webhook"
+    depends_on:
+      trogon-sink-github:
+        condition: service_healthy
+    restart: unless-stopped
+    profiles:
+      - dev
 
 volumes:
   nats_data:

rsworkspace/.dockerignore

@@ -0,0 +1,27 @@
+# Rust build artifacts — largest offender, can be many GBs
+target/
+
+# Dev tooling
+.git/
+.github/
+.cargo/
+
+# Test/CI artifacts
+lcov.info
+coverage.xml
+*.profraw
+*.profdata
+mutants.out*/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Environment files with secrets
+.env
+.env.*
+!.env.example

rsworkspace/Cargo.lock

@@ -5,13 +5,15 @@
 pub enum ServiceName {
     AcpNatsStdio,
     AcpNatsWs,
+    TrogonSinkGithub,
 }
 
 impl ServiceName {
     pub fn as_str(self) -> &'static str {
         match self {
             Self::AcpNatsStdio => "acp-nats-stdio",
             Self::AcpNatsWs => "acp-nats-ws",
+            Self::TrogonSinkGithub => "trogon-sink-github",
         }
     }
 }
@@ -30,11 +32,16 @@ mod tests {
     fn as_str_returns_expected_values() {
         assert_eq!(ServiceName::AcpNatsStdio.as_str(), "acp-nats-stdio");
         assert_eq!(ServiceName::AcpNatsWs.as_str(), "acp-nats-ws");
+        assert_eq!(ServiceName::TrogonSinkGithub.as_str(), "trogon-sink-github");
     }
 
     #[test]
     fn display_delegates_to_as_str() {
         assert_eq!(format!("{}", ServiceName::AcpNatsStdio), "acp-nats-stdio");
         assert_eq!(format!("{}", ServiceName::AcpNatsWs), "acp-nats-ws");
+        assert_eq!(
+            format!("{}", ServiceName::TrogonSinkGithub),
+            "trogon-sink-github"
+        );
     }
 }

rsworkspace/crates/acp-telemetry/src/service_name.rs

@@ -51,7 +51,7 @@ impl JetStreamPublisher for NatsJetStreamClient {
         subject: S,
         headers: HeaderMap,
         payload: Bytes,
-    ) -> Result<PublishAckFuture, PublishError> {
+    ) -> Result<Self::AckFuture, Self::PublishError> {
         self.context
             .publish_with_headers(subject, headers, payload)
             .await

rsworkspace/crates/trogon-nats/src/jetstream/client.rs

@@ -246,6 +246,10 @@ impl MockJetStreamPublisher {
             .map(|m| m.payload.clone())
             .collect()
     }
+
+    pub fn published_messages(&self) -> Vec<MockPublishedJsMessage> {
+        self.published.lock().unwrap().clone()
+    }
 }
 
 impl Default for MockJetStreamPublisher {

rsworkspace/crates/trogon-nats/src/jetstream/mocks.rs

@@ -21,7 +21,8 @@ pub trait JetStreamContext: Send + Sync + Clone + 'static {
 
 pub trait JetStreamPublisher: Send + Sync + Clone + 'static {
     type PublishError: Error + Send + Sync;
-    type AckFuture: IntoFuture<Output = Result<PublishAck, Self::PublishError>> + Send;
+    type AckFuture: IntoFuture<Output = Result<PublishAck, Self::PublishError>, IntoFuture: Send>
+        + Send;
 
     fn publish_with_headers<S: ToSubject + Send>(
         &self,