feat: Implement AT Protocol firehose (com.atproto.sync.subscribeRepos) with event broadcasting and a WebSocket endpoint

PDSharp.Core/Firehose.fs

···
+namespace PDSharp.Core
+
+open System
+open System.Threading
+
+/// Event stream (firehose) for com.atproto.sync.subscribeRepos
+module Firehose =
+
+  /// Commit event sent to subscribers
+  type CommitEvent = {
+    Seq : int64
+    Did : string
+    Rev : string
+    Commit : Cid
+    Blocks : byte[]
+    Time : DateTimeOffset
+  }
+
+  /// Mutable sequence counter for firehose events
+  let private seqCounter = ref 0L
+
+  /// Get the next sequence number (thread-safe, monotonic)
+  let nextSeq () : int64 = Interlocked.Increment(seqCounter)
+
+  /// Get current sequence without incrementing (for cursor resume)
+  let currentSeq () : int64 = seqCounter.Value
+
+  /// Create a commit event for a repository write
+  let createCommitEvent (did : string) (rev : string) (commitCid : Cid) (carBytes : byte[]) : CommitEvent = {
+    Seq = nextSeq ()
+    Did = did
+    Rev = rev
+    Commit = commitCid
+    Blocks = carBytes
+    Time = DateTimeOffset.UtcNow
+  }
+
+  /// Encode a commit event to DAG-CBOR bytes for WebSocket transmission
+  /// Format follows AT Protocol #commit message structure
+  let encodeEvent (event : CommitEvent) : byte[] =
+    let eventMap : Map<string, obj> =
+      Map.ofList [
+        "$type", box "com.atproto.sync.subscribeRepos#commit"
+        "seq", box event.Seq
+        "did", box event.Did
+        "rev", box event.Rev
+        "commit", box event.Commit
+        "blocks", box event.Blocks
+        "time", box (event.Time.ToString("o"))
+      ]
+
+    DagCbor.encode eventMap
+
+  /// Reset sequence counter (for testing)
+  let resetSeq () =
+    Interlocked.Exchange(seqCounter, 0L) |> ignore

PDSharp.Core/PDSharp.Core.fsproj

···
         <Compile Include="Car.fs" />
         <Compile Include="AtUri.fs" />
         <Compile Include="Repository.fs" />
+        <Compile Include="Firehose.fs" />
         <Compile Include="DidResolver.fs" />
         <Compile Include="Library.fs" />
     </ItemGroup>

PDSharp.Tests/Firehose.Tests.fs

···
+module Firehose.Tests
+
+open Xunit
+open PDSharp.Core
+open PDSharp.Core.Firehose
+open PDSharp.Core.Crypto
+
+[<Fact>]
+let ``nextSeq monotonically increases`` () =
+  resetSeq ()
+  let seq1 = nextSeq ()
+  let seq2 = nextSeq ()
+  let seq3 = nextSeq ()
+
+  Assert.Equal(1L, seq1)
+  Assert.Equal(2L, seq2)
+  Assert.Equal(3L, seq3)
+
+[<Fact>]
+let ``currentSeq returns without incrementing`` () =
+  resetSeq ()
+  let _ = nextSeq () // 1
+  let _ = nextSeq () // 2
+  let current = currentSeq ()
+  let next = nextSeq ()
+
+  Assert.Equal(2L, current)
+  Assert.Equal(3L, next)
+
+[<Fact>]
+let ``createCommitEvent has correct fields`` () =
+  resetSeq ()
+  let hash = sha256Str "test"
+  let cid = Cid.FromHash hash
+  let carBytes = [| 0x01uy; 0x02uy |]
+
+  let event = createCommitEvent "did:web:test" "rev123" cid carBytes
+
+  Assert.Equal(1L, event.Seq)
+  Assert.Equal("did:web:test", event.Did)
+  Assert.Equal("rev123", event.Rev)
+  Assert.Equal<byte[]>(cid.Bytes, event.Commit.Bytes)
+  Assert.Equal<byte[]>(carBytes, event.Blocks)
+
+[<Fact>]
+let ``encodeEvent produces valid CBOR`` () =
+  resetSeq ()
+  let hash = sha256Str "test"
+  let cid = Cid.FromHash hash
+  let carBytes = [| 0x01uy; 0x02uy |]
+  let event = createCommitEvent "did:web:test" "rev123" cid carBytes
+  let encoded = encodeEvent event
+
+  Assert.True(encoded.Length > 0)
+  Assert.True(encoded.[0] >= 0xa0uy, "Should encode as CBOR map")

PDSharp.Tests/PDSharp.Tests.fsproj

···
     <Compile Include="AtUri.Tests.fs" />
     <Compile Include="Repository.Tests.fs" />
     <Compile Include="Car.Tests.fs" />
+    <Compile Include="Firehose.Tests.fs" />
     <Compile Include="Program.fs" />
   </ItemGroup>
 

PDSharp/Program.fs

···
 open PDSharp.Core.Repository
 open PDSharp.Core.Mst
 open PDSharp.Core.Crypto
+open PDSharp.Core.Firehose
 
 module App =
   /// Repo state per DID: MST root, collections, current rev, head commit CID
···
   let blockStore = MemoryBlockStore()
   let mutable signingKeys : Map<string, EcKeyPair> = Map.empty
 
+  // Firehose subscriber management
+  open System.Net.WebSockets
+  open System.Collections.Concurrent
+
+  /// Connected WebSocket subscribers
+  let subscribers = ConcurrentDictionary<Guid, WebSocket>()
+
+  /// Broadcast a commit event to all connected subscribers
+  let broadcastEvent (event : CommitEvent) =
+    let eventBytes = encodeEvent event
+    let segment = ArraySegment<byte>(eventBytes)
+
+    for kvp in subscribers do
+      let ws = kvp.Value
+
+      if ws.State = WebSocketState.Open then
+        try
+          ws.SendAsync(segment, WebSocketMessageType.Binary, true, Threading.CancellationToken.None)
+          |> Async.AwaitTask
+          |> Async.RunSynchronously
+        with _ ->
+          subscribers.TryRemove(kvp.Key) |> ignore
+
   let getOrCreateKey (did : string) =
     match Map.tryFind did signingKeys with
     | Some k -> k
···
       }
 
       repos <- Map.add did updatedRepo repos
+
+      let! allBlocks = (blockStore :> IBlockStore).GetAllCidsAndData()
+      let carBytes = Car.createCar [ commitCid ] allBlocks
+      let event = createCommitEvent did newRev commitCid carBytes
+      broadcastEvent event
 
       let uri = $"at://{did}/{request.collection}/{rkey}"
       ctx.SetStatusCode 200
···
 
         repos <- Map.add did updatedRepo repos
 
+        let! allBlocks = (blockStore :> IBlockStore).GetAllCidsAndData()
+        let carBytes = Car.createCar [ commitCid ] allBlocks
+        let event = createCommitEvent did newRev commitCid carBytes
+        broadcastEvent event
+
         ctx.SetStatusCode 200
 
         return!
···
               return! ctx.WriteBytesAsync data
     }
 
+  /// subscribeRepos: WebSocket firehose endpoint
+  let subscribeReposHandler : HttpHandler =
+    fun next ctx -> task {
+      if ctx.WebSockets.IsWebSocketRequest then
+        let cursor =
+          match ctx.Request.Query.TryGetValue("cursor") with
+          | true, v when not (String.IsNullOrWhiteSpace(v.ToString())) ->
+            Int64.TryParse(v.ToString())
+            |> function
+              | true, n -> Some n
+              | _ -> None
+          | _ -> None
+
+        let! webSocket = ctx.WebSockets.AcceptWebSocketAsync()
+        let id = Guid.NewGuid()
+        subscribers.TryAdd(id, webSocket) |> ignore
+
+        let buffer = Array.zeroCreate<byte> 1024
+
+        try
+          let mutable loop = true
+
+          while loop && webSocket.State = WebSocketState.Open do
+            let! result = webSocket.ReceiveAsync(ArraySegment(buffer), Threading.CancellationToken.None)
+
+            if result.MessageType = WebSocketMessageType.Close then
+              loop <- false
+        finally
+          subscribers.TryRemove(id) |> ignore
+
+          if webSocket.State = WebSocketState.Open then
+            webSocket.CloseAsync(WebSocketCloseStatus.NormalClosure, "Closed", Threading.CancellationToken.None)
+            |> Async.AwaitTask
+            |> Async.RunSynchronously
+
+        return Some ctx
+      else
+        ctx.SetStatusCode 400
+
+        return!
+          json
+            {
+              error = "InvalidRequest"
+              message = "WebSocket upgrade required"
+            }
+            next
+            ctx
+    }
+
   let webApp =
     choose [
       GET
···
       GET >=> route "/xrpc/com.atproto.sync.getRepo" >=> getRepoHandler
       GET >=> route "/xrpc/com.atproto.sync.getBlocks" >=> getBlocksHandler
       GET >=> route "/xrpc/com.atproto.sync.getBlob" >=> getBlobHandler
+      GET >=> route "/xrpc/com.atproto.sync.subscribeRepos" >=> subscribeReposHandler
       route "/" >=> text "PDSharp PDS is running."
       RequestErrors.NOT_FOUND "Not Found"
     ]
 
-  let configureApp (app : IApplicationBuilder) = app.UseGiraffe webApp
+  let configureApp (app : IApplicationBuilder) =
+    app.UseWebSockets() |> ignore
+    app.UseGiraffe webApp
 
   let configureServices (config : AppConfig) (services : IServiceCollection) =
     services.AddGiraffe() |> ignore

README.md

···
 
 The server will start at `http://localhost:5000`.
 
-### Verify
+## API Testing
 
-Check the `describeServer` endpoint:
+### Server Info
 
 ```bash
 curl http://localhost:5000/xrpc/com.atproto.server.describeServer
+```
+
+### Record Operations
+
+**Create a record:**
+
+```bash
+curl -X POST http://localhost:5000/xrpc/com.atproto.repo.createRecord \
+  -H "Content-Type: application/json" \
+  -d '{"repo":"did:web:test","collection":"app.bsky.feed.post","record":{"text":"Hello, ATProto!"}}'
+```
+
+**Get a record** (use the rkey from createRecord response):
+
+```bash
+curl "http://localhost:5000/xrpc/com.atproto.repo.getRecord?repo=did:web:test&collection=app.bsky.feed.post&rkey=<RKEY>"
+```
+
+**Put a record** (upsert with explicit rkey):
+
+```bash
+curl -X POST http://localhost:5000/xrpc/com.atproto.repo.putRecord \
+  -H "Content-Type: application/json" \
+  -d '{"repo":"did:web:test","collection":"app.bsky.feed.post","rkey":"my-post","record":{"text":"Updated!"}}'
+```
+
+### Sync & CAR Export
+
+**Get entire repository as CAR:**
+
+```bash
+curl "http://localhost:5000/xrpc/com.atproto.sync.getRepo?did=did:web:test" -o repo.car
+```
+
+**Get specific blocks** (comma-separated CIDs):
+
+```bash
+curl "http://localhost:5000/xrpc/com.atproto.sync.getBlocks?did=did:web:test&cids=<CID1>,<CID2>" -o blocks.car
+```
+
+**Get a blob by CID:**
+
+```bash
+curl "http://localhost:5000/xrpc/com.atproto.sync.getBlob?did=did:web:test&cid=<BLOB_CID>"
+```
+
+### Firehose (WebSocket)
+
+Subscribe to real-time commit events using [websocat](https://github.com/vi/websocat):
+
+```bash
+# Install websocat (macOS)
+brew install websocat
+
+# Connect to firehose
+websocat ws://localhost:5000/xrpc/com.atproto.sync.subscribeRepos
+```
+
+Then create/update records in another terminal to see CBOR-encoded commit events stream in real-time.
+
+**With cursor for resumption:**
+
+```bash
+websocat "ws://localhost:5000/xrpc/com.atproto.sync.subscribeRepos?cursor=5"
 ```
 
 ## Configuration

roadmap.txt

···
 --------------------------------------------------------------------------------
 Milestone G: subscribeRepos Firehose
 --------------------------------------------------------------------------------
-- Monotonic sequence number + commit event generation
-- WebSocket streaming for subscribeRepos
+- [x] Monotonic sequence number + commit event generation
+- [x] WebSocket streaming for subscribeRepos
 DoD: Relay/client receives commit events after writes
 --------------------------------------------------------------------------------
 Milestone H: Account + Sessions
···
 [x] MST producing deterministic root CIDs
 [x] putRecord + blockstore operational
 [x] CAR export + sync endpoints
-[ ] subscribeRepos firehose
+[x] subscribeRepos firehose
 [ ] Authentication (createAccount, createSession)
 [ ] Lexicon validation
 [ ] Domain + TLS configured