From 86f495c3fd16dcfacb8d56c052db34f0e89fccd5 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sun, 15 Jun 2025 09:38:11 +0100 Subject: [PATCH 1/3] Document preamble setup order --- README.md | 1 + docs/preamble-validator.md | 9 +++++++++ src/server.rs | 3 +-- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3730e278..e1b941b7 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ reduce this boilerplate through layered abstractions: - **Transport adapter** built on Tokio I/O - **Framing layer** for length‑prefixed or custom frames - **Connection preamble** with customizable validation callbacks [[docs](docs/preamble-validator.md)] +- Call `with_preamble::()` before registering success or failure callbacks - **Serialization engine** using `bincode` or a `wire-rs` wrapper - **Routing engine** that dispatches messages by ID - **Handler invocation** with extractor support diff --git a/docs/preamble-validator.md b/docs/preamble-validator.md index f0905fd2..5bdef4d0 100644 --- a/docs/preamble-validator.md +++ b/docs/preamble-validator.md @@ -31,3 +31,12 @@ sequenceDiagram In the tests, a `HotlinePreamble` struct illustrates the pattern, but any preamble type may be used. Register callbacks via `on_preamble_decode_success` and `on_preamble_decode_failure` on `WireframeServer`. + +## Call Order + +`WireframeServer::with_preamble` must be called **before** +registering callbacks with `on_preamble_decode_success` or +`on_preamble_decode_failure`. The method converts the server to use a +custom preamble type, dropping any callbacks configured on the default +`()` preamble. Registering callbacks after calling `with_preamble` +ensures they are retained. diff --git a/src/server.rs b/src/server.rs index 98c195f8..cc1895bf 100644 --- a/src/server.rs +++ b/src/server.rs @@ -88,8 +88,7 @@ where /// Convert this server to parse a custom preamble `T`. /// - /// Call this before registering preamble handlers, otherwise any - /// previously configured callbacks will be dropped. + /// Call this before registering preamble handlers. Calling it later drops any previously configured callbacks. #[must_use] pub fn with_preamble(self) -> WireframeServer where From 6489ea3caecdce6326d2d1aaf164874d88d2f832 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sun, 15 Jun 2025 09:55:20 +0100 Subject: [PATCH 2/3] Clarify preamble callback docs --- docs/preamble-validator.md | 4 ++-- src/server.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/preamble-validator.md b/docs/preamble-validator.md index 5bdef4d0..f6561504 100644 --- a/docs/preamble-validator.md +++ b/docs/preamble-validator.md @@ -34,9 +34,9 @@ and `on_preamble_decode_failure` on `WireframeServer`. ## Call Order -`WireframeServer::with_preamble` must be called **before** +`WireframeServer::with_preamble::()` must be called **before** registering callbacks with `on_preamble_decode_success` or `on_preamble_decode_failure`. The method converts the server to use a custom preamble type, dropping any callbacks configured on the default -`()` preamble. Registering callbacks after calling `with_preamble` +`()` preamble. Registering callbacks after calling `with_preamble::()` ensures they are retained. diff --git a/src/server.rs b/src/server.rs index cc1895bf..84ab1d67 100644 --- a/src/server.rs +++ b/src/server.rs @@ -88,7 +88,7 @@ where /// Convert this server to parse a custom preamble `T`. /// - /// Call this before registering preamble handlers. Calling it later drops any previously configured callbacks. + /// Call this before registering preamble callbacks. Calling it later drops any previously configured callbacks. #[must_use] pub fn with_preamble(self) -> WireframeServer where From 17c5dbfebdaa6d19c8c10a2e4617e5803b2b3cc7 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sun, 15 Jun 2025 10:43:47 +0100 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`cod?= =?UTF-8?q?ex/fix-callback-handler-reset-in-with=5Fpreamble`=20(#46)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 Add docstrings to `codex/fix-callback-handler-reset-in-with_preamble` Docstrings generation was requested by @leynos. * https://github.com/leynos/wireframe/pull/45#issuecomment-2973591635 The following files were modified: * `src/server.rs` * Tidy docstring --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Leynos --- src/server.rs | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/server.rs b/src/server.rs index 84ab1d67..a8c61b13 100644 --- a/src/server.rs +++ b/src/server.rs @@ -86,9 +86,23 @@ where } } - /// Convert this server to parse a custom preamble `T`. + /// Converts the server to use a custom preamble type for incoming connections. /// - /// Call this before registering preamble callbacks. Calling it later drops any previously configured callbacks. + /// Calling this method will drop any previously configured preamble decode callbacks. Use it before registering preamble handlers if you wish to retain them. + /// + /// # Type Parameters + /// + /// * `T` – The type to decode as the connection preamble; must implement `bincode::Decode<()>`, `Send`, and `'static`. + /// + /// # Returns + /// + /// A new `WireframeServer` instance configured to decode preambles of type `T`. + /// + /// # Examples + /// + /// ``` + /// let server = WireframeServer::new(factory).with_preamble::(); + /// ``` #[must_use] pub fn with_preamble(self) -> WireframeServer where