From 7d8c2e9550f64439528206c4c206e42a0b6da496 Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Sun, 29 Jun 2025 01:48:11 +0100
Subject: [PATCH 1/3] Document WireframeProtocol builder hook

---
 README.md | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d42a4a6e..5d9bcc55 100644
--- a/README.md
+++ b/README.md
@@ -133,16 +133,28 @@ let app = WireframeApp::new()?
 
 ## Connection Lifecycle
 
-`WireframeApp` can run callbacks when a connection is opened or closed. The
-state produced by `on_connection_setup` is passed to `on_connection_teardown`
-when the connection ends.
+Protocol callbacks are consolidated under the `WireframeProtocol` trait,
+replacing the individual `on_connection_setup`/`on_connection_teardown`
+closures. A protocol implementation registers hooks for connection setup, frame
+mutation and command completion.
 
 ```rust
-    let app = WireframeApp::new()
-        .on_connection_setup(|| async { 42u32 })
-        .on_connection_teardown(|state| async move {
-            println!("closing with {state}");
-        });
+pub trait WireframeProtocol: Send + Sync + 'static {
+    type Frame: FrameLike;
+    type ProtocolError;
+
+    fn on_connection_setup(
+        &self,
+        handle: PushHandle<Self::Frame>,
+        ctx: &mut ConnectionContext,
+    );
+
+    fn before_send(&self, frame: &mut Self::Frame, ctx: &mut ConnectionContext);
+
+    fn on_command_end(&self, ctx: &mut ConnectionContext);
+}
+
+let app = WireframeApp::new().with_protocol(MySqlProtocolImpl);
 ```
 
 ## Custom Extractors

From 5fdc05839b199a0fb3a9c350bc4e80dd498338bf Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Sun, 29 Jun 2025 02:14:29 +0100
Subject: [PATCH 2/3] Document protocol trait integration

---
 README.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5d9bcc55..da73c57b 100644
--- a/README.md
+++ b/README.md
@@ -135,8 +135,11 @@ let app = WireframeApp::new()?
 
 Protocol callbacks are consolidated under the `WireframeProtocol` trait,
 replacing the individual `on_connection_setup`/`on_connection_teardown`
-closures. A protocol implementation registers hooks for connection setup, frame
-mutation and command completion.
+closures. The trait methods are synchronous so the trait remains object safe,
+but callbacks can spawn asynchronous tasks when needed. A protocol
+implementation registers hooks for connection setup, frame mutation and command
+completion. The associated `ProtocolError` type is used by other parts of the
+API, such as request handling.
 
 ```rust
 pub trait WireframeProtocol: Send + Sync + 'static {
@@ -154,6 +157,28 @@ pub trait WireframeProtocol: Send + Sync + 'static {
     fn on_command_end(&self, ctx: &mut ConnectionContext);
 }
 
+struct MySqlProtocolImpl;
+
+impl WireframeProtocol for MySqlProtocolImpl {
+    type Frame = Vec<u8>;
+    type ProtocolError = ();
+
+    fn on_connection_setup(
+        &self,
+        handle: PushHandle<Self::Frame>,
+        _ctx: &mut ConnectionContext,
+    ) {
+        // Spawn an async task to send a heartbeat after setup
+        tokio::spawn(async move {
+            let _ = handle.push_high_priority(b"ping".to_vec()).await;
+        });
+    }
+
+    fn before_send(&self, _frame: &mut Self::Frame, _ctx: &mut ConnectionContext) {}
+
+    fn on_command_end(&self, _ctx: &mut ConnectionContext) {}
+}
+
 let app = WireframeApp::new().with_protocol(MySqlProtocolImpl);
 ```
 

From f16ec8ca2900eb7c2947a78b5d1ff58bcad91e22 Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Sun, 29 Jun 2025 02:14:37 +0100
Subject: [PATCH 3/3] Fix protocol example code fencing

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index da73c57b..4394a552 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,9 @@ impl WireframeProtocol for MySqlProtocolImpl {
     fn on_command_end(&self, _ctx: &mut ConnectionContext) {}
 }
 
+```
+
+```rust
 let app = WireframeApp::new().with_protocol(MySqlProtocolImpl);
 ```