DEV Community: tengxgfyrz67s

Rendering and Performance Optimization in euv

tengxgfyrz67s — Tue, 30 Jun 2026 16:14:56 +0000

Project Code：https://github.com/euv-dev/euv

Performance is a critical concern for any frontend framework. Users expect applications to be fast, responsive, and smooth. euv addresses performance through its virtual DOM implementation, which uses a variety of optimization strategies including incremental rendering, keyed diffing, and event delegation. This article takes a deep dive into how euv's renderer works and how you can write code that takes full advantage of its optimization capabilities.

Understanding the Rendering Pipeline

euv's rendering pipeline follows a straightforward but highly optimized process:

State Change: A reactive signal is updated via set().
Re-render Trigger: The signal change triggers a re-render of the affected component tree.
Virtual DOM Diff: The new virtual DOM tree is compared against the previous one.
Minimal DOM Updates: Only the differences are applied to the real DOM.

This pipeline ensures that expensive DOM operations are minimized. Instead of replacing entire sections of the page, euv computes the smallest possible set of changes and applies them precisely.

Incremental Rendering

euv supports incremental rendering, which means that only the parts of the UI that have actually changed are updated. When a reactive signal changes, euv doesn't re-render the entire application — it traces the signal's dependencies and re-renders only the components that depend on it.

Consider this example:

let count: Signal<i32> = use_signal(|| 0);
count.get();
count.set(42);

When count.set(42) is called, euv knows that only the components reading count need to be re-rendered. Components that don't depend on count are left untouched. This is the fundamental optimization that makes reactive UIs efficient.

Full Replacement Rendering

In some cases, euv may need to perform a full replacement render. This happens when the structure of the component tree changes significantly — for example, when a conditional branch changes from one component type to another. Full replacement rendering replaces the entire subtree rather than trying to patch it incrementally.

While more expensive than incremental updates, full replacement rendering is still efficient because it operates on the virtual DOM first and only applies the necessary changes to the real DOM.

Keyed Diffing

One of the most important optimizations in any virtual DOM system is how it handles list diffing. When rendering dynamic lists, euv uses keyed diffing to minimize DOM operations. By assigning stable keys to list items, euv can track which items were added, removed, or reordered, and apply only the necessary changes.

Without keys, the diffing algorithm has to assume that items at the same position correspond to each other, which can lead to unnecessary DOM updates when items are reordered. With keys, euv can correctly identify moved items and simply reposition them rather than destroying and recreating them.

Event Delegation

euv uses event delegation to handle user interactions efficiently. Instead of attaching individual event listeners to every interactive element, euv attaches a single listener at a higher level in the DOM tree and dispatches events to the appropriate handlers based on the event target.

This approach has several benefits:

Memory efficiency: Fewer event listeners means less memory usage.
Dynamic content: Newly created elements automatically inherit event handling without needing to attach listeners.
Performance: No overhead from managing hundreds or thousands of individual listeners.

When you write event handlers like onclick, oninput, or onchange in the html! macro, euv automatically registers them through the delegation system:

html! {
    button {
        onclick: |e| { /* handle click */ }
        "Click me"
    }
}

DOM Cleanup

When components are unmounted — for example, when a conditional branch removes a component from the tree — euv performs DOM cleanup to remove the associated DOM elements and detach any resources. This prevents memory leaks and ensures that the DOM stays clean.

The use_cleanup hook allows you to register cleanup callbacks that run when a component is unmounted:

use_cleanup(|| {
    // Clean up resources when this component is unmounted
});

This is particularly important for components that set up timers, intervals, or subscriptions.

Performance Best Practices

Use Reactive Signals Wisely

Signals are the foundation of euv's reactivity system. Use use_signal to create signals and watch! to observe them:

let count: Signal<i32> = use_signal(|| 0);
watch!(count, |c| {
    // React to count changes
});

Keep signals focused on the data they represent. Avoid creating signals for values that don't change — use plain values instead.

Minimize Signal Updates

Each signal update triggers a re-render. Batch related updates when possible:

let count: Signal<i32> = use_signal(|| 0);
// Instead of multiple separate updates:
count.set(count.get() + 1);
count.set(count.get() + 1);
// Consider batching into a single update

Leverage watch! for Derived State

Use watch! to create derived state that automatically updates when its dependencies change:

let celsius: Signal<f64> = use_signal(|| 0.0);
let fahrenheit: Signal<f64> = use_signal(|| 32.0);
watch!(celsius, |c| {
    fahrenheit.set(c * 9.0 / 5.0 + 32.0);
});

This pattern ensures that derived values are always consistent with their sources, and the watch! macro handles the subscription and cleanup automatically.

Use Keyed Lists

When rendering lists, always provide stable keys for items that may be reordered or filtered. This allows euv's keyed diffing algorithm to minimize DOM operations.

Avoid Unnecessary DOM Depth

Deeply nested DOM structures are harder to diff and update. Keep your component trees as flat as possible while maintaining readability.

Measuring Performance

When optimizing performance, always measure before and after your changes. Use browser developer tools to profile your application and identify bottlenecks. Common areas to investigate include:

Excessive re-renders: Components re-rendering when their inputs haven't changed.
Large list updates: Lists with many items that are frequently updated.
Expensive computations: Calculations performed during rendering that could be cached.

Conclusion

euv's rendering engine is designed for performance. Through incremental rendering, keyed diffing, event delegation, and DOM cleanup, it minimizes expensive DOM operations and keeps your application responsive. By understanding how the rendering pipeline works and following best practices — using reactive signals wisely, leveraging watch! for derived state, and keeping component trees flat — you can build euv applications that are fast and smooth even as they grow in complexity. In the next article, we'll explore the virtual DOM internals in greater detail to understand how these optimizations are implemented under the hood.

Project Code：https://github.com/euv-dev/euv

CSS Variables and Var Macros in euv

tengxgfyrz67s — Tue, 30 Jun 2026 16:07:28 +0000

Project Code：https://github.com/euv-dev/euv

euv provides powerful primitives for managing CSS dynamically at runtime. The css-vars! and var! macros bridge the gap between reactive Rust state and CSS styling, enabling theming, responsive design, and dynamic visual effects — all without leaving your Rust code.

Why Dynamic CSS Variables?

Traditional CSS is static. Once a stylesheet is loaded, values are fixed. Modern web applications, however, need runtime control over styles: dark mode toggles, user-customized themes, animated transitions driven by application state, and responsive layouts that go beyond media queries.

CSS custom properties (--my-var) solve part of the problem by allowing JavaScript to set and read CSS values at runtime. euv's css-vars! and var! macros build on this foundation with full reactive integration.

The `css-vars!` Macro

The css-vars! macro defines CSS custom properties that can be applied to elements. It generates CSS variable declarations that are injected into the document.

Basic Usage

css-vars! {
    --primary-color: "#3498db";
    --spacing-unit: "8px";
    --border-radius: "4px";
}

This generates CSS custom properties that can be referenced anywhere in your stylesheets using var(--primary-color), var(--spacing-unit), etc.

How It Works

When css-vars! is invoked, euv:

Generates CSS custom property declarations.
Injects them into the document's styles.
Makes them available for use in any CSS rule or inline style.

These variables become part of the document's CSS environment and can be consumed by any element.

Scoping CSS Variables

You can scope CSS variables to specific components or elements by combining css-vars! with euv's component system. Variables defined within a component's context apply only to that element and its descendants.

The `var!` Macro: Reactive Variables

While css-vars! defines static CSS custom properties, var! creates reactive CSS variables — variables that automatically update when their source signals change.

Basic Usage

let primary_color: Signal<String> = use_signal(|| "#3498db".to_string());
var!(primary_color);

The var! macro takes a Signal<String> and creates a CSS variable that tracks the signal's value. When primary_color changes via set(), the CSS variable is automatically updated in the DOM.

How It Works Internally

When var! is called:

It reads the current value of the signal.
Sets the corresponding CSS custom property on the target element.
Subscribes to the signal for future changes.
When the signal's value changes, the CSS property is updated automatically.

This creates a seamless reactive binding between Rust state and CSS.

Combining `css-vars!` and `var!`

The real power emerges when you use both macros together. Define your CSS variable structure with css-vars! and drive values reactively with var!:

css-vars! {
    --primary-color: "#3498db";
    --spacing-unit: "8px";
}

let theme_color: Signal<String> = use_signal(|| "#3498db".to_string());
var!(theme_color);

Now --primary-color is defined as a CSS custom property, and theme_color signal drives its value reactively.

Dynamic Theming

One of the most compelling use cases for CSS variables in euv is dynamic theming. Here's how you can build a theme switcher:

// Define theme colors as signals
let bg_color: Signal<String> = use_signal(|| "#ffffff".to_string());
let text_color: Signal<String> = use_signal(|| "#333333".to_string());
let accent_color: Signal<String> = use_signal(|| "#3498db".to_string());

// Create reactive CSS variables
var!(bg_color);
var!(text_color);
var!(accent_color);

// Switch to dark mode
fn switch_to_dark_mode() {
    batch(|| {
        bg_color.set("#1a1a2e".to_string());
        text_color.set("#eaeaea".to_string());
        accent_color.set("#e94560".to_string());
    });
}

// Switch to light mode
fn switch_to_light_mode() {
    batch(|| {
        bg_color.set("#ffffff".to_string());
        text_color.set("#333333".to_string());
        accent_color.set("#3498db".to_string());
    });
}

Notice the use of batch to coordinate all color updates at once. This ensures that all CSS variables are updated together, preventing visual glitches from partial theme application.

Responsive Spacing and Layout

CSS variables driven by signals can also power responsive layouts that adapt to application state:

let spacing_unit: Signal<String> = use_signal(|| "8px".to_string());
var!(spacing_unit);

// Increase spacing on large screens
watch!(window_width, |w: i32| {
    if w > 1200 {
        spacing_unit.set("16px".to_string());
    } else if w > 768 {
        spacing_unit.set("12px".to_string());
    } else {
        spacing_unit.set("8px".to_string());
    }
});

Animation Control with CSS Variables

euv comes with built-in CSS keyframe animations: euv-spin, euv-fade-in, euv-scale-in, euv-pulse, euv-slide-up, euv-slide-left, euv-fade-in-up, euv-progress, and euv-shimmer. You can control these animations dynamically using var!:

let spin_duration: Signal<String> = use_signal(|| "1s".to_string());
var!(spin_duration);

// Speed up the spin animation on hover
watch!(is_hovering, |hovering: bool| {
    if hovering {
        spin_duration.set("0.3s".to_string());
    } else {
        spin_duration.set("1s".to_string());
    }
});

Usage with the class! macro:

class! {
    pub c_anim_spin { animation: "euv-spin 1s linear infinite"; }
}

Custom Keyframe Animations

For animations beyond the built-in set, euv provides Css::inject_css to inject custom @keyframes rules:

Css::inject_css("@keyframes my-bounce {
    0%, 100% { transform: translateY(0); }
    50% { transform: translateY(-20px); }
}");

You can then reference these custom animations in your class! definitions:

class! {
    pub c_anim_bounce { animation: "my-bounce 0.5s ease-in-out infinite"; }
}

Integrating with the `class!` Macro

The class! macro generates CSS class definitions. Combined with var!, you can create classes that incorporate reactive CSS variables:

class! {
    pub c_card {
        display: "flex";
        padding: "10px";
        background-color: var(--card-bg);
        color: var(--card-text);
    }
}

// Drive the CSS variables reactively
let card_bg: Signal<String> = use_signal(|| "#ffffff".to_string());
let card_text: Signal<String> = use_signal(|| "#333333".to_string());
var!(card_bg);
var!(card_text);

Practical Examples

Example 1: Dark Mode Toggle

let dark_mode: Signal<bool> = use_signal(|| false);

let bg: Signal<String> = use_signal(|| "#ffffff".to_string());
let fg: Signal<String> = use_signal(|| "#333333".to_string());
var!(bg);
var!(fg);

watch!(dark_mode, |is_dark: bool| {
    batch(|| {
        if is_dark {
            bg.set("#121212".to_string());
            fg.set("#e0e0e0".to_string());
        } else {
            bg.set("#ffffff".to_string());
            fg.set("#333333".to_string());
        }
    });
});

Example 2: User-Configurable Accent Color

let accent: Signal<String> = use_signal(|| "#3498db".to_string());
var!(accent);

// When user picks a new color from a color picker:
fn on_color_pick(new_color: String) {
    accent.set(new_color);
}

Example 3: Progress Bar with Reactive Styling

let progress: Signal<f64> = use_signal(|| 0.0);
let progress_color: Signal<String> = use_signal(|| "#3498db".to_string());

var!(progress);
var!(progress_color);

watch!(progress, |p: f64| {
    if p < 0.3 {
        progress_color.set("#e74c3c".to_string());
    } else if p < 0.7 {
        progress_color.set("#f39c12".to_string());
    } else {
        progress_color.set("#2ecc71".to_string());
    }
});

Summary

css-vars! defines CSS custom properties that can be used throughout your stylesheets.
var! creates reactive bindings between Signal<String> values and CSS custom properties, automatically updating the DOM when signals change.
Combine both macros to build dynamic themes, responsive layouts, and animation-driven UIs.
Use batch to coordinate multiple CSS variable updates and prevent visual glitches.
Custom keyframe animations can be injected with Css::inject_css("@keyframes my-bounce { ... }").
Built-in animations include euv-spin, euv-fade-in, euv-scale-in, euv-pulse, euv-slide-up, euv-slide-left, euv-fade-in-up, euv-progress, and euv-shimmer.

CSS variables in euv transform styling from a static concern into a first-class part of your reactive application state, enabling rich, dynamic user experiences with minimal code.

Project Code：https://github.com/euv-dev/euv

Cookie and Session Management in Hyperlane

tengxgfyrz67s — Tue, 30 Jun 2026 15:59:52 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

Cookie and session management are fundamental aspects of modern web development. They enable stateful interactions in the inherently stateless HTTP protocol, allowing servers to remember users across multiple requests. In the hyperlane framework, cookie handling is built directly into the request and response APIs, providing a clean and efficient way to manage user sessions.

This article covers everything you need to know about working with cookies in hyperlane — from reading incoming cookies to creating and sending new ones using the powerful CookieBuilder API.

Reading Cookies from Requests

Getting All Cookies

Hyperlane makes it easy to retrieve all cookies from an incoming HTTP request:

let cookies = ctx.get_request().try_get_cookies();

This returns all cookies sent by the client as part of the request. The try_get_cookies method parses the Cookie header and returns the cookie collection.

Getting a Specific Cookie

When you need to access a particular cookie by name, use:

let cookie = ctx.get_request().try_get_cookie("session_id");

This returns an Option type — Some(cookie_value) if the cookie exists, or None if it doesn't. This pattern encourages proper error handling and avoids panics from missing cookies.

Creating Cookies with CookieBuilder

Hyperlane provides a fluent CookieBuilder API for creating cookies with various attributes. The builder pattern allows you to chain configuration calls for a clean, readable syntax.

Basic Cookie Creation

let cookie = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();

This creates a cookie named session_id with the value abc123, scoped to the root path and marked as HttpOnly (inaccessible to JavaScript, providing XSS protection).

Full Cookie Configuration

The CookieBuilder supports all standard cookie attributes:

let cookie = CookieBuilder::new("session", "token123")
    .set_expires("Wed, 21 Oct 2025 07:28:00 GMT")
    .set_domain("example.com")
    .set_same_site("Strict")
    .set_max_age(3600)
    .set_path("/")
    .secure()
    .http_only()
    .build();

Let's break down each attribute:

set_expires — Sets the cookie's expiration date in HTTP date format. After this date, the browser will no longer send the cookie.
set_domain — Specifies which domain the cookie is valid for. The cookie will only be sent to the specified domain and its subdomains.
set_same_site — Controls cross-site request behavior. "Strict" prevents the cookie from being sent in cross-site requests, while "Lax" allows it for top-level navigations.
set_max_age — Sets the cookie's lifetime in seconds. After this duration, the cookie expires. This is preferred over set_expires as it is relative to the current time.
set_path — Restricts the cookie to a specific URL path. The cookie is only sent for requests to paths under this prefix.
secure() — Marks the cookie as secure, meaning it will only be sent over HTTPS connections.
http_only() — Marks the cookie as HttpOnly, preventing access from JavaScript to mitigate XSS attacks.

Clearing Cookies

To delete a cookie from the client, create a new cookie with the same name but with an empty value and max_age of 0:

let clear_cookie = CookieBuilder::new("session", "")
    .set_max_age(0)
    .build();

This tells the browser to immediately expire the cookie, effectively removing it.

Sending Cookies in Responses

Once you have built a cookie, you attach it to the response using the Set-Cookie header:

let cookie = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();

ctx.get_mut_response().set_header(SET_COOKIE, &cookie);

The SET_COOKIE constant is the standard header name for setting cookies. If you need to set multiple cookies, use add_header instead of set_header to append additional Set-Cookie headers:

ctx.get_mut_response().add_header(SET_COOKIE, &cookie1);
ctx.get_mut_response().add_header(SET_COOKIE, &cookie2);

Complete Session Management Example

Here is a complete example showing a login handler that creates a session cookie and a logout handler that clears it:

#[route("/login")]
struct LoginHandler;

impl ServerHook for LoginHandler {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // Verify credentials (simplified for demonstration)
        let body = ctx.get_request().get_body_string();

        // Create a session cookie on successful authentication
        let session_cookie = CookieBuilder::new("session_id", "abc123")
            .set_path("/")
            .http_only()
            .secure()
            .build();

        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200)
            .set_header(SET_COOKIE, &session_cookie)
            .set_body("Login successful");

        let data = ctx.get_mut_response().build();
        stream.try_send(data).await;

        Status::Continue
    }
}

#[route("/logout")]
struct LogoutHandler;

impl ServerHook for LogoutHandler {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // Clear the session cookie
        let clear_cookie = CookieBuilder::new("session_id", "")
            .set_max_age(0)
            .build();

        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200)
            .set_header(SET_COOKIE, &clear_cookie)
            .set_body("Logged out successfully");

        let data = ctx.get_mut_response().build();
        stream.try_send(data).await;

        Status::Continue
    }
}

Cookie-Based Authentication Middleware

You can combine cookie reading with authentication logic to create middleware that protects routes:

struct AuthMiddleware;

impl ServerHook for AuthMiddleware {
    async fn new(_: &mut Stream, ctx: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let session_cookie = ctx.get_request().try_get_cookie("session_id");

        match session_cookie {
            Some(session_id) if !session_id.is_empty() => {
                // Session exists — proceed to the next handler
                Status::Continue
            }
            _ => {
                // No valid session — reject the request
                let data = ctx.get_mut_response()
                    .set_status_code(401)
                    .set_body("Unauthorized")
                    .build();

                if stream.try_send(data).await.is_err() {
                    stream.set_closed(true);
                }

                Status::Reject
            }
        }
    }
}

server.request_middleware::<AuthMiddleware>();

Session Management Best Practices

Always use HttpOnly for session cookies. This prevents JavaScript access and mitigates XSS-based session theft.
Use Secure flag in production. Session cookies should only be transmitted over HTTPS to prevent interception.
Set SameSite attribute. Use "Strict" or "Lax" to protect against CSRF attacks. "Strict" provides the strongest protection but may affect user experience.
Use Max-Age instead of Expires. Max-Age is relative to the current time and avoids clock synchronization issues between server and client.
Keep session identifiers unpredictable. Use cryptographically random values for session IDs rather than sequential or predictable values.
Implement proper session expiration. Set reasonable Max-Age values and always clear cookies on logout by setting Max-Age to 0.
Scope cookies appropriately. Use set_path to limit cookie transmission to only the paths that need them.

Combining Cookies with Other Hyperlane Features

Cookies and Attributes

You can use hyperlane's attribute system to store session data that persists across multiple requests on the same connection:

ctx.set_attribute("user_id", "123");
let user_id: Option<String> = ctx.try_get_attribute("user_id");

Cookies and SSE

When working with Server-Sent Events, cookies set in the initial response are sent as part of the response headers:

let session_cookie = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();

let data = ctx.get_mut_response()
    .set_header(CONTENT_TYPE, TEXT_EVENT_STREAM)
    .set_header(SET_COOKIE, &session_cookie)
    .set_body(Vec::new())
    .build();

stream.try_send(data).await;

Conclusion

Hyperlane provides a comprehensive and ergonomic API for cookie and session management. The CookieBuilder fluent interface makes it easy to create cookies with all standard attributes, while the request API provides safe methods for reading incoming cookies. By following best practices — using HttpOnly, Secure, and SameSite attributes — you can build secure session management systems that protect your users from common web vulnerabilities.

Whether you are building a simple login system or a complex multi-tenant application, hyperlane's cookie management tools give you everything you need to maintain stateful interactions in your web applications.

Project Code：https://github.com/hyperlane-dev/hyperlane

TypeScript Interoperability in euv

tengxgfyrz67s — Tue, 30 Jun 2026 15:51:59 +0000

Project Code：https://github.com/euv-dev/euv

euv is a Rust + WebAssembly frontend UI framework that compiles Rust code into WASM modules running in the browser. While the core UI logic is written in Rust, real-world projects often need to interoperate with the vast TypeScript/JavaScript ecosystem — from calling JavaScript libraries to exposing Rust functions to TypeScript code. This article explores how euv leverages wasm-bindgen, js-sys, and web-sys to enable seamless interoperability between Rust and TypeScript.

Understanding the WASM Interop Layer
Calling JavaScript from Rust with js-sys
Accessing Browser APIs with web-sys
Exposing Rust Functions to TypeScript
Working with JavaScript Promises and Async
Practical Patterns for TS Interop
Conclusion

Understanding the WASM Interop Layer

When euv compiles to WebAssembly, the resulting .wasm module communicates with JavaScript through a thin glue layer generated by wasm-bindgen. This tool automatically generates JavaScript wrapper functions that handle the marshaling of types across the Rust-JavaScript boundary.

The key crates involved in this interop are:

wasm-bindgen — Generates the JS glue code and provides the #[wasm_bindgen] attribute for exposing Rust functions to JavaScript
js-sys — Provides raw bindings to JavaScript's standard built-in objects (Object, Array, Promise, JSON, Math, etc.)
web-sys — Provides raw bindings to the browser's Web APIs (Window, Document, Storage, fetch, etc.)

In euv, all types from js-sys and web-sys are re-exported through use euv::*, so you never need to add these crates as direct dependencies. The framework handles the interop plumbing for you.

Calling JavaScript from Rust with js-sys

The js-sys crate provides bindings to JavaScript's core built-in objects. Through euv's re-exports, you can access these directly.

Working with JavaScript Objects

use euv::*;

// Create a JavaScript object
let obj: Object = Object::new();

// Set properties on the object
Reflect::set(&obj, &"name".into(), &"euv".into()).unwrap();

// Get properties from the object
let name: JsValue = Reflect::get(&obj, &"name".into()).unwrap();
let name_string: String = name.as_string().unwrap_or_default();

Working with JavaScript Arrays

use euv::*;

// Create a JavaScript array
let arr: Array = Array::new();

// Push values to the array
arr.push(&"Rust".into());
arr.push(&"WASM".into());
arr.push(&"euv".into());

// Iterate over the array
arr.for_each(&mut |value: JsValue, _index: u32, _array: &Array| {
    web_sys::console::log_1(&value);
});

// Get array length
let length: u32 = arr.length();

Using JSON

use euv::*;

// Parse a JSON string
let json_string: String = r#"{"name": "euv", "version": "0.1"}"#.to_string();
let json_value: JsValue = JSON::parse(&json_string).unwrap();

// Stringify a JavaScript object
let obj: Object = Object::new();
Reflect::set(&obj, &"framework".into(), &"euv".into()).unwrap();
let stringified: String = JSON::stringify(&obj).unwrap().as_string().unwrap_or_default();

Using JavaScript Promises

use euv::*;

// Create a JavaScript promise that resolves after a delay
let promise: Promise = Promise::new(&mut |resolve: Function, _reject: Function| {
    let window: Window = window().expect("no global window exists");
    let closure: Closure<dyn Fn()> = Closure::new(move || {
        let _ = resolve.call0(&JsValue::NULL);
    });
    window.set_timeout_with_callback_and_timeout_and_arguments_0(
        closure.as_ref().unchecked_ref(),
        1000,
    ).expect("set_timeout failed");
    closure.forget();
});

// Convert to JsFuture and await it
let future: JsFuture = JsFuture::from(promise);
match future.await {
    Ok(value) => {
        web_sys::console::log_1(&"Promise resolved!".into());
    }
    Err(err) => {
        web_sys::console::log_1(&err);
    }
}

Accessing Browser APIs with web-sys

The web-sys crate provides comprehensive bindings to browser APIs. euv re-exports these through use euv::* and pre-enables commonly used features in its Cargo.toml.

Window and Document Access

use euv::*;

let win: Window = window().expect("no global window exists");
let doc: Document = win.document().expect("should have a document");

Navigation and Routing

use euv::*;

let win: Window = window().expect("no global window exists");
let location: Location = win.location();

// Get current hash route
let hash: String = location.hash().unwrap_or_default();

// Set hash route (page navigation)
let _ = location.set_hash("#/about");

Local Storage

use euv::*;

let win: Window = window().expect("no global window exists");
let storage: Option<Storage> = win.local_storage().unwrap_or_default();

if let Some(storage) = storage {
    // Write
    let _ = storage.set_item("key", "value");
    // Read
    let value: Option<String> = storage.get_item("key").unwrap_or_default();
    // Delete
    let _ = storage.remove_item("key");
}

Making HTTP Requests with fetch

use euv::*;

let loading: Signal<bool> = use_signal(|| false);
let loading_updater: Signal<bool> = loading;
let data: Signal<String> = use_signal(|| "".to_string());
let data_updater: Signal<String> = data;
let error: Signal<String> = use_signal(|| "".to_string());
let error_updater: Signal<String> = error;

button {
    onclick: move |_event: Event| {
        loading_updater.set(true);
        error_updater.set("".to_string());
        let data_updater_clone: Signal<String> = data_updater;
        let loading_updater_clone: Signal<bool> = loading_updater;
        let error_updater_clone: Signal<String> = error_updater;
        spawn_local(async move {
            let window: Window = window().expect("no global window exists");
            let promise: Promise = window.fetch_with_str("https://httpbin.org/get");
            let future: JsFuture = JsFuture::from(promise);
            match future.await {
                Ok(response) => {
                    let resp: Response = response.dyn_into().unwrap();
                    let json_promise: Promise = resp.json().unwrap();
                    let json_future: JsFuture = JsFuture::from(json_promise);
                    match json_future.await {
                        Ok(json) => {
                            let json_string: String = JSON::stringify(&json).unwrap().as_string().unwrap_or_default();
                            data_updater_clone.set(json_string);
                        }
                        Err(_) => {
                            error_updater_clone.set("Failed to parse JSON".to_string());
                        }
                    }
                }
                Err(_) => {
                    error_updater_clone.set("Network request failed".to_string());
                }
            }
            loading_updater_clone.set(false);
        });
    }
    "Fetch Data"
}

In this example, spawn_local is euv's re-export of wasm_bindgen_futures::spawn_local, and JsFuture, JSON, Promise, Window, Response are all available through use euv::* without needing separate js-sys or web-sys dependencies.

Exposing Rust Functions to TypeScript

To make Rust functions callable from TypeScript, you use the #[wasm_bindgen] attribute. This generates the necessary JavaScript glue code.

Basic Function Export

use euv::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn main() {
    console_error_panic_hook::set_once();
    mount("#app", app);
}

The #[wasm_bindgen] attribute on the main function tells wasm-bindgen to generate a JavaScript wrapper. This function can then be called from TypeScript:

import init, { main } from './pkg/my_euv_app.js';

await init();
main();

Exporting Functions with Parameters

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

From TypeScript:

import { greet } from './pkg/my_euv_app.js';

const message = greet('World'); // "Hello, World!"

Exporting Functions that Return JsValue

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn get_config() -> JsValue {
    let obj = js_sys::Object::new();
    js_sys::Reflect::set(&obj, &"name".into(), &"euv".into()).unwrap();
    js_sys::Reflect::set(&obj, &"version".into(), &"0.1".into()).unwrap();
    obj.into()
}

Working with JavaScript Promises and Async

euv's spawn_local function (re-exported from wasm_bindgen_futures::spawn_local) is the key to running asynchronous Rust code in the WASM environment. It allows you to spawn Rust futures that integrate seamlessly with the JavaScript event loop.

Fetching Data Asynchronously

use euv::*;

spawn_local(async move {
    let window: Window = window().expect("no global window exists");
    let promise: Promise = window.fetch_with_str("https://httpbin.org/get");
    let future: JsFuture = JsFuture::from(promise);
    match future.await {
        Ok(response) => {
            let resp: Response = response.dyn_into().unwrap();
            let json_promise: Promise = resp.json().unwrap();
            let json_future: JsFuture = JsFuture::from(json_promise);
            match json_future.await {
                Ok(json) => {
                    let json_string: String = JSON::stringify(&json).unwrap().as_string().unwrap_or_default();
                    data_updater_clone.set(json_string);
                }
                Err(_) => {
                    error_updater_clone.set("Failed to parse JSON".to_string());
                }
            }
        }
        Err(_) => {
            error_updater_clone.set("Network request failed".to_string());
        }
    }
    loading_updater_clone.set(false);
});

[!tip]

All browser APIs are accessed through web-sys crate — euv pre-enables common web-sys features (such as Window, Document, Storage, Clipboard, Navigator, FileReader, FileList, IntersectionObserver, etc.) in its Cargo.toml, and re-exports them through use euv::*. You never need to manually add web-sys as a dependency.

Using spawn_local with Signals

A common pattern is to use spawn_local to perform async operations and then update reactive signals when the operation completes:

let loading: Signal<bool> = use_signal(|| false);
let loading_updater: Signal<bool> = loading;
let data: Signal<String> = use_signal(|| "".to_string());
let data_updater: Signal<String> = data;
let error: Signal<String> = use_signal(|| "".to_string());
let error_updater: Signal<String> = error;

button {
    onclick: move |_event: Event| {
        loading_updater.set(true);
        error_updater.set("".to_string());
        let data_updater_clone: Signal<String> = data_updater;
        let loading_updater_clone: Signal<bool> = loading_updater;
        let error_updater_clone: Signal<String> = error_updater;
        spawn_local(async move {
            // ... async operations ...
            data_updater_clone.set("result".to_string());
            loading_updater_clone.set(false);
        });
    }
    "Fetch Data"
}

[!warning]

Signal clones used in async closures must be cloned outside the closure and then moved in, otherwise borrow conflicts will occur.

Practical Patterns for TS Interop

Pattern 1: Calling JavaScript Libraries

When you need to use a JavaScript library (e.g., a charting library or date picker), you can create Rust bindings using #[wasm_bindgen] extern blocks:

use wasm_bindgen::prelude::*;

#[wasm_bindgen(module = "some-js-library")]
extern "C" {
    #[wasm_bindgen(js_name = "someFunction")]
    pub fn some_function(input: &str) -> JsValue;
}

Then call it from Rust:

let result: JsValue = some_function("input");
let result_string: String = result.as_string().unwrap_or_default();

Pattern 2: Passing Callbacks to JavaScript

use wasm_bindgen::prelude::*;

let callback: Closure<dyn FnMut(JsValue)> = Closure::new(move |value: JsValue| {
    let value_string: String = value.as_string().unwrap_or_default();
    data_updater.set(value_string);
});

// Pass the callback to a JavaScript function
some_js_function(callback.as_ref().unchecked_ref());

// Important: forget the closure to prevent it from being dropped
// (only if you want it to persist beyond the current scope)
// callback.forget();

Pattern 3: Using web-sys with Event Handlers

use euv::*;

html! {
    input {
        r#type: "text"
        placeholder: "Enter text"
        oninput: move |event: Event| {
            if let Some(target) = event.target()
                && let Ok(input) = target.clone().dyn_into::<HtmlInputElement>() {
                    name_signal.set(input.value());
                }
        }
    }
}

In this example, dyn_into::<HtmlInputElement>() comes from wasm_bindgen::JsCast, which is re-exported through euv. The HtmlInputElement type is from web-sys, also re-exported through use euv::*.

Pattern 4: Combining Browser APIs with Reactive Signals

let tab: Signal<String> = use_signal(|| {
    let win: Window = window().expect("no global window exists");
    let location: Location = win.location();
    let hash: String = location.hash().unwrap_or_default();
    if hash == "#/settings" {
        "settings".to_string()
    } else {
        "info".to_string()
    }
});

html! {
    div {
        match { tab.get().as_str() } {
            "info" => { div { "Information content" } }
            _ => { div { "Settings content" } }
        }
    }
}

This pattern derives the initial signal value from the browser's URL hash, ensuring the UI state matches the URL on page load.

Pattern 5: Persisting State to Local Storage

let name: Signal<String> = use_signal(|| {
    let win: Window = window().expect("no global window exists");
    let storage: Option<Storage> = win.local_storage().unwrap_or_default();
    if let Some(storage) = storage {
        storage.get_item("user_name").unwrap_or_default()
    } else {
        "".to_string()
    }
});

Conclusion

euv's TypeScript interoperability is built on the solid foundation of wasm-bindgen, js-sys, and web-sys. Through euv's re-export system (use euv::*), you get seamless access to:

JavaScript built-in objects (Object, Array, Promise, JSON, Math, etc.) via js-sys
Browser APIs (Window, Document, Location, Storage, fetch, Navigator, etc.) via web-sys
Async operations via spawn_local (re-exported from wasm_bindgen_futures)
Type casting via JsCast trait (dyn_ref, dyn_into)
Function export via #[wasm_bindgen] attribute

The key takeaway is that euv handles all the interop plumbing for you. You never need to add js-sys or web-sys as direct dependencies — everything is available through use euv::*. This allows you to focus on writing your application logic in Rust while still having full access to the JavaScript ecosystem when needed.

When building euv applications that need TypeScript interop, remember to:

Use #[wasm_bindgen] to expose Rust functions to JavaScript
Use spawn_local for async operations that need to interact with JavaScript APIs
Clone signals before moving them into async closures
Use dyn_ref and dyn_into for type-safe event handling
Leverage euv's re-exports to avoid managing js-sys and web-sys dependencies directly

Project Code：https://github.com/euv-dev/euv

Utilities and Ecosystem of Hyperlane

tengxgfyrz67s — Tue, 30 Jun 2026 15:43:22 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

Hyperlane is not just a standalone HTTP server library — it is supported by a rich ecosystem of utilities, plugins, and companion crates that extend its capabilities. This article provides a comprehensive overview of the recommended tools in the Hyperlane ecosystem, explaining what each one does and how it integrates with your Hyperlane-based applications.

The Hyperlane Ecosystem at a Glance

The Hyperlane ecosystem includes tools for:

Utility functions — General-purpose helpers for common tasks
Logging — Structured logging tailored for Hyperlane
Time handling — Date and time utilities
Process management — Recoverable spawn and thread pool
HTTP utilities — HTTP request helpers and WebSocket plugins
Data encoding — Binary encoding/decoding
File operations — File reading, writing, and manipulation
URL handling — URL encoding/decoding
API documentation — OpenAPI/Swagger integration
Validation — Chinese ID card validation
Server management — Server lifecycle management

Core Utilities

hyperlane-utils

The hyperlane-utils crate provides a collection of general-purpose utility functions that complement the Hyperlane framework. These utilities cover common patterns that arise in web server development, such as string manipulation, data transformation, and common algorithmic helpers.

std-macro-extensions

std-macro-extensions extends Rust's standard library with additional macros that simplify common patterns. When building Hyperlane applications, these macros can reduce boilerplate and make your code more concise.

future-fn

future-fn provides utilities for working with async functions and futures. In the context of Hyperlane, it helps manage complex async middleware chains and handler compositions.

Logging and Time

hyperlane-log

hyperlane-log is a logging solution designed specifically for Hyperlane applications. It provides structured logging with configurable output formats and levels. Integrating it into your Hyperlane server gives you visibility into request processing, middleware execution, and error conditions.

hyperlane-time

hyperlane-time offers date and time utilities optimized for server-side use. It handles time formatting, parsing, and timezone conversions — essential for HTTP date headers, logging timestamps, and session management.

color-output

color-output adds colored terminal output to your logs and console messages. This is particularly useful during development when you want to quickly distinguish between different log levels or message types.

Process and Task Management

recoverable-spawn

recoverable-spawn provides a spawn mechanism that can recover from task panics. In a Hyperlane server, this ensures that a panic in one request handler doesn't crash the entire server process. It aligns with Hyperlane's TaskPanicHook pattern:

struct TaskPanicHook;

impl ServerHook for TaskPanicHook {
    async fn new(_: &mut Stream, ctx: &mut Context) -> Self {
        let error = ctx.try_get_task_panic_data().unwrap_or_default();
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let data = ctx.get_mut_response().set_status_code(500).set_body("panic").build();
        stream.try_send(data).await;
        Status::Continue
    }
}

server.task_panic::<TaskPanicHook>();

recoverable-thread-pool

recoverable-thread-pool extends the recoverable spawn concept to thread pools. For Hyperlane applications that offload CPU-intensive work to a thread pool, this crate ensures that panics in worker threads are caught and handled gracefully.

HTTP and Network Utilities

http-request

http-request simplifies making HTTP requests from within your Hyperlane application. Whether you need to call external APIs, proxy requests, or implement a reverse proxy, this utility provides a clean interface for HTTP client operations.

hyperlane-plugin-websocket

hyperlane-plugin-websocket is a dedicated WebSocket plugin for Hyperlane. While Hyperlane has built-in WebSocket support, this plugin extends it with additional features like automatic reconnection, message framing, and broadcast capabilities.

hyperlane-broadcast

hyperlane-broadcast provides a broadcast mechanism for sending messages to multiple connected clients. This is useful for implementing chat systems, real-time notifications, and live updates. It integrates with Hyperlane's SSE and WebSocket capabilities.

urlencoding

urlencoding handles URL encoding and decoding, which is essential for processing query parameters, path segments, and form data in HTTP requests.

Data Processing

bin-encode-decode

bin-encode-decode provides binary encoding and decoding utilities. For Hyperlane applications that need to handle binary protocols or process binary request/response bodies, this tool simplifies the conversion between binary and text formats.

file-operation

file-operation offers a set of file manipulation utilities. Combined with Hyperlane's static file serving capabilities, this crate helps manage file uploads, downloads, and transformations:

let file_path = format!("{static_path}{path}");
let file_extension = FileExtension::get_extension_name(&file_path);
let content_type = FileExtension::parse(&file_extension).get_content_type();
let file_data = tokio::fs::read_to_string(&file_path).await.unwrap();
ctx.get_mut_response().set_body(file_data);

chunkify

chunkify splits data into chunks for streaming or batch processing. This is particularly useful when implementing SSE or streaming file downloads in Hyperlane:

let data = ctx.get_mut_response()
    .set_header(CONTENT_TYPE, TEXT_EVENT_STREAM)
    .set_body(Vec::new())
    .build();
stream.try_send(data).await;

for i in 0..10 {
    let body = format!("data:{i}{HTTP_DOUBLE_BR}");
    stream.try_send(&body).await;
}

compare-version

compare-version provides semantic version comparison utilities. This is useful for implementing API versioning in your Hyperlane application, allowing you to route requests based on the requested API version.

API Documentation

utoipa

utoipa is an OpenAPI documentation generator for Rust. Integrating it with Hyperlane allows you to automatically generate OpenAPI/Swagger specifications for your API endpoints. This is invaluable for API discoverability and client code generation.

Validation

china_identification_card

china_identification_card provides validation for Chinese national ID card numbers. If your Hyperlane application serves users in China and needs to validate identity documents, this utility handles the validation logic.

Server Management

server-manager

server-manager provides server lifecycle management utilities. It complements Hyperlane's ServerControlHook by offering additional features for managing server instances, monitoring health, and orchestrating deployments.

clonelicious

clonelicious simplifies cloning operations for complex data structures. In Hyperlane applications where you need to clone Context or Stream data for parallel processing, this crate reduces the boilerplate.

Integrating Ecosystem Tools with Hyperlane

The recommended tools are designed to work together seamlessly. Here's how you might combine several of them in a typical Hyperlane application:

Use hyperlane-log for structured request/response logging
Use hyperlane-time for timestamp generation in logs and HTTP headers
Use http-request for outbound API calls from your handlers
Use hyperlane-plugin-websocket for enhanced WebSocket features
Use utoipa for API documentation generation
Use recoverable-spawn for robust task spawning
Use urlencoding for safe URL parameter handling
Use file-operation and chunkify for file serving and streaming

Project Structure with Ecosystem Tools

The recommended project directory structure accommodates these ecosystem tools:

├── application/controller/domain/exception/mapper/middleware/model/repository/service/utils/view
├── bootstrap/application/framework
├── config/application/framework
├── plugin/database/env/logger/mysql/postgresql/process/redis
├── resources/docker/env/sql/static/templates

The plugin directory is where you integrate ecosystem tools like hyperlane-log, hyperlane-broadcast, and hyperlane-plugin-websocket. The utils directory under application is where you place utility wrappers around crates like urlencoding, bin-encode-decode, and compare-version.

Installation

Most ecosystem tools can be added via Cargo:

cargo add hyperlane-utils
cargo add hyperlane-log
cargo add hyperlane-time
cargo add recoverable-spawn
cargo add http-request
cargo add hyperlane-plugin-websocket
cargo add utoipa

Conclusion

The Hyperlane ecosystem provides a comprehensive set of tools that extend the core framework's capabilities. From logging and time handling to WebSocket plugins and API documentation, these crates are designed to work together and with Hyperlane's core APIs. By leveraging these ecosystem tools, you can build feature-rich, production-ready web applications with less custom code and more reliability.

Project Code：https://github.com/hyperlane-dev/hyperlane

The html! Macro in Depth

tengxgfyrz67s — Sun, 28 Jun 2026 03:43:58 +0000

Project Code：https://github.com/euv-dev/euv

Introduction to the html! Macro

The html! macro is the heart of euv's templating system. It provides a declarative, HTML-like syntax directly within Rust code, allowing you to construct virtual DOM nodes using a familiar structure. The macro compiles into efficient VirtualNode constructions, giving you the best of both worlds: the readability of HTML and the type safety of Rust.

The basic syntax is intuitive:

html! {
    div {
        h1 { "Hello, euv!" }
        p { "Welcome to the html! macro." }
    }
}

This produces a VirtualNode tree with a div element containing an h1 and a p element.

Basic Syntax Rules

Nesting Elements

Elements are nested using curly braces. Each element can contain child elements or text content:

html! {
    div {
        header {
            nav {
                a { href: "/home" "Home" }
            }
        }
        main {
            p { "Content here" }
        }
    }
}

Text Content

Text content is placed directly inside curly braces after the element name:

html! {
    p { "This is a paragraph with text content." }
}

Attributes

Attributes are specified using the key: value syntax inside the element's curly braces, before any child content:

html! {
    input {
        type: "text",
        placeholder: "Enter your name"
    }
}

Conditional Rendering with if/else

The html! macro supports conditional rendering using if/else blocks. The condition must be wrapped in curly braces, and the else branch is required — if you want nothing to display, use an empty string "":

html! {
    div {
        if { show.get() } {
            div { "Visible" }
        } else {
            ""
        }
    }
}

In this example, the div with "Visible" text is only rendered when show.get() returns true. Otherwise, an empty string is rendered.

Important Rules for if/else

The condition expression must be wrapped in {}: if { condition }
The else branch cannot be omitted. If you want nothing, use else { "" }
Both branches must return valid content (either a VirtualNode or a string)

// Correct: else branch present
html! {
    if { is_logged_in.get() } {
        div { "Welcome back!" }
    } else {
        div { "Please log in." }
    }
}

// Correct: empty else branch
html! {
    if { show_banner.get() } {
        div { "Special offer!" }
    } else {
        ""
    }
}

Conditional Rendering with match

For more complex conditional logic, the html! macro supports match expressions. A match block must include a wildcard _ branch to handle all remaining cases:

html! {
    div {
        match { user_type.get().as_str() } {
            "guest" => {
                div { "Guest" }
            }
            "admin" => {
                div { "Admin" }
            }
            _ => {
                div { "Unknown" }
            }
        }
    }
}

Important Rules for match

The match expression must be wrapped in {}: match { expression }
Each arm must return valid content
A wildcard _ branch is required to handle all unmatched cases

html! {
    match { status.get().as_str() } {
        "loading" => {
            div { "Loading..." }
        }
        "success" => {
            div { "Data loaded successfully!" }
        }
        "error" => {
            div { "An error occurred." }
        }
        _ => {
            div { "Unknown status." }
        }
    }
}

List Rendering with for Loops

The html! macro supports for loops for rendering lists of items. The iterable expression must be wrapped in curly braces:

html! {
    ul {
        for item in { items.get() } {
            li { item }
        }
    }
}

Iterating with Index

You can also iterate with an index using .iter().enumerate():

html! {
    ol {
        for (index, item) in { items.get().iter().enumerate() } {
            li { index item }
        }
    }
}

Important Rules for for Loops

The iterable expression must be wrapped in {}: for item in { expression }
The loop body must return valid content
You can destructure the iterator, e.g., for (index, item) in { ... }

html! {
    table {
        tbody {
            for (index, item) in { users.get().iter().enumerate() } {
                tr {
                    td { index }
                    td { item }
                }
            }
        }
    }
}

Reactive Attribute Values

The html! macro supports reactive attribute values. When an attribute depends on a signal, the attribute automatically updates when the signal changes:

fn app() -> VirtualNode {
    let count: Signal<i32> = use_signal(|| 0);

    html! {
        div {
            h1 { "Counter" }
            button {
                onclick: move |event: Event| {
                    count.set(count.get() + 1);
                }
                "Increment"
            }
        }
    }
}

In this example, the button's onclick handler reads and updates the count signal. When the signal changes, euv automatically re-renders the affected parts of the UI.

Nesting Components

The html! macro supports nesting custom components inside the template. Components are referenced by their function name:

#[derive(Clone, Default)]
struct MyCardProps {
    title: &'static str,
}

#[component]
pub fn my_card(node: VirtualNode<MyCardProps>) -> VirtualNode {
    let MyCardProps { title, .. } = node.try_get_props().unwrap_or_default();
    let children: VirtualNode = node.try_get_child_node();
    html! {
        div {
            h3 { title }
            children
        }
    }
}

fn app() -> VirtualNode {
    html! {
        div {
            MyCard {
                title: "Welcome"
                p { "This is content inside a card." }
            }
        }
    }
}

Components can receive props as named attributes and children as nested content. The component function receives a VirtualNode that carries both the props and child nodes.

Combining All Features

Here's a more comprehensive example that combines conditional rendering, list rendering, and component nesting:

use euv::*;

#[derive(Clone, Default)]
struct TodoItemProps {
    text: &'static str,
}

#[component]
pub fn todo_item(node: VirtualNode<TodoItemProps>) -> VirtualNode {
    let TodoItemProps { text, .. } = node.try_get_props().unwrap_or_default();
    html! {
        li { text }
    }
}

fn app() -> VirtualNode {
    let items: Signal<Vec<String>> = use_signal(|| vec![
        "Learn euv".to_string(),
        "Build an app".to_string(),
    ]);
    let show_list: Signal<bool> = use_signal(|| true);

    html! {
        div {
            h1 { "My Todo List" }

            if { show_list.get() } {
                ul {
                    for item in { items.get() } {
                        TodoItem {
                            text: item
                        }
                    }
                }
            } else {
                p { "List is hidden." }
            }

            button {
                onclick: use_toggle(show_list)
                "Toggle List"
            }
        }
    }
}

mount("#app", app);

This example demonstrates:

Component definition: todo_item is a reusable component with typed props
Conditional rendering: The list is shown/hidden based on show_list
List rendering: for loop iterates over the items
Event handling: use_toggle toggles the boolean signal
Component nesting: TodoItem is used inside the html! macro

Summary

The html! macro is a powerful and flexible templating system:

Basic syntax: Nest elements with {}, place text content directly, specify attributes with key: value
if/else: Conditional rendering with mandatory else branch (use "" for empty)
match: Multi-branch conditional rendering with required _ wildcard
for loops: List rendering with { } wrapped iterables, supports index via .enumerate()
Reactive attributes: Attributes automatically update when signals change
Component nesting: Use custom components directly in the template with props and children

The html! macro, combined with euv's reactive signals and component system, provides everything you need to build complex, interactive user interfaces in Rust.

Project Code：https://github.com/euv-dev/euv

WebAssembly Deep Dive: How euv Leverages WASM

tengxgfyrz67s — Sun, 28 Jun 2026 03:36:47 +0000

Project Code：https://github.com/euv-dev/euv

WebAssembly (WASM) is a binary instruction format that runs in modern web browsers at near-native speed. euv is built from the ground up to target WASM, compiling Rust code into efficient browser-executable modules. This article takes a deep dive into how euv uses WebAssembly under the hood, covering the compilation pipeline, memory management, performance characteristics, and the runtime architecture that makes it all work.

The WASM Compilation Pipeline
Memory Management in WASM
How euv Renders via WASM
Performance Characteristics
The Runtime Architecture
Working with JavaScript from WASM
Conclusion

The WASM Compilation Pipeline

The journey from Rust source code to a running euv application in the browser involves several steps:

Rust Source (.rs)
    ↓ rustc (with wasm32-unknown-unknown target)
WASM Binary (.wasm)
    ↓ wasm-bindgen
JavaScript Glue (.js) + WASM Binary
    ↓ Browser loads via ES module
Running Application

Step 1: Project Configuration

Every euv project starts with the proper Cargo.toml configuration:

[package]
edition = "2024"

[dependencies]
euv = "*"
lombok-macros = "*"

[lib]
crate-type = ["cdylib", "rlib"]

The crate-type = ["cdylib"] entry tells the Rust compiler to produce a dynamic library suitable for WASM. The rlib type allows the crate to also be used as a Rust library (for testing, for example).

Step 2: The Application Entry Point

use euv::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn main() {
    console_error_panic_hook::set_once();
    mount("#app", app);
}

The #[wasm_bindgen] attribute generates JavaScript glue code for the main function. The console_error_panic_hook::set_once() call ensures that Rust panics are logged to the browser console — essential for debugging WASM applications.

Step 3: Building with wasm-pack

wasm-pack build --target web --out-dir www/pkg

The --target web flag produces output that can be loaded directly in the browser using ES modules. After a successful build, the pkg/ directory contains:

my_app_bg.wasm — the compiled WebAssembly binary
my_app.js — the JavaScript glue code
package.json — metadata for the package

Step 4: Loading in the Browser

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>euv app</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module">
      import init, { main } from './pkg/euv_example.js';
      await init();
      main();
    </script>
  </body>
</html>

The init() function loads and instantiates the WASM module, and main() starts the euv application.

Step 5: Development with euv CLI

For a smoother development experience, euv provides a CLI tool:

cargo install euv-cli
euv run --crate-path ./example --www-dir ./www --port 80

The CLI handles building, file watching, hot reloading, and serving. Build modes are controlled via flags:

# Development build (debug info enabled, optimizations disabled)
euv run --crate-path ./example --www-dir ./www --port 80 --dev

# Release build (optimizations enabled, debug info disabled)
euv run --crate-path ./example --www-dir ./www --port 80 --release

# Profiling build (optimizations enabled, debug info enabled)
euv run --crate-path ./example --www-dir ./www --port 80 --profiling

Memory Management in WASM

WebAssembly has a fundamentally different memory model than JavaScript. Understanding this model is key to writing efficient euv applications.

Linear Memory

WASM operates on a contiguous block of memory called "linear memory." This is a resizable ArrayBuffer that the WASM module can read and write. All data structures — strings, objects, arrays — are serialized into this linear memory as bytes.

┌──────────────────────────────────────────────┐
│              Linear Memory                    │
├──────────┬──────────┬──────────┬─────────────┤
│ Strings  │ Objects  │ Arrays   │ Free Space  │
└──────────┴──────────┴──────────┴─────────────┘
              ↑ Stack    ↑ Heap

Rust's Ownership Model in WASM

Rust's ownership model works the same way in WASM as it does natively. When a Rust value goes out of scope, its memory is automatically freed. This is particularly powerful in the WASM context because:

No garbage collector — Unlike JavaScript, there's no GC pause or overhead
Deterministic deallocation — Memory is freed exactly when the value goes out of scope
No memory leaks — The ownership system prevents leaks at compile time (in safe Rust)

fn app() -> VirtualNode {
    // count is allocated when use_signal is called
    let count: Signal<i32> = use_signal(|| 0);
    let count_updater: Signal<i32> = count;

    html! {
        div {
            // count is used here, so it stays alive
            span { count }
            button {
                onclick: move |_event: Event| {
                    let current: i32 = count_updater.get();
                    count_updater.set(current + 1);
                }
                "Increment"
            }
        }
    }
    // When this function returns, local variables are dropped
    // But count lives on because it's captured in the closure
}

Memory and the Virtual DOM

The virtual DOM in euv is a Rust data structure that lives in WASM's linear memory. When the renderer compares the old and new virtual DOM trees, it's doing this comparison entirely within WASM memory — no JavaScript round-trips needed.

// The VirtualNode is a Rust enum stored in WASM memory
enum VirtualNode<T> {
    Element {
        tag: Tag,
        attributes: Vec<AttributeEntry>,
        children: Vec<VirtualNode<T>>,
        key: Option<String>,
        props: Option<T>,
    },
    Text(TextNode),
    Fragment(Vec<VirtualNode<T>>),
    Dynamic(Rc<RefCell<DynamicNode<T>>>),
    Empty,
}

The Dynamic variant is particularly interesting — it uses Rc<RefCell<>> to allow shared mutable access to dynamic nodes that need to re-render when their dependencies change.

Signal Memory Layout

Signals in euv are reference-counted reactive containers:

// Signal<T> internally holds:
// - The current value of type T
// - A set of subscriber callbacks (closures)
// - Reference counting for shared ownership

let count: Signal<i32> = use_signal(|| 0);
// count is a smart pointer (Rc<SignalInner<i32>>)
// SignalInner<i32> { value: 0, subscribers: Vec<...>, ... }

When you clone a signal (let count_updater: Signal<i32> = count;), you're incrementing the reference count, not copying the value. This makes signal cloning essentially free.

How euv Renders via WASM

The Rendering Process

When mount("#app", app) is called, the following happens:

The renderer reads the CSS selector #app (via web-sys)
It calls app() to get the initial VirtualNode tree
It creates real DOM elements matching the virtual tree
It inserts those elements into the #app container

use euv::*;

fn app() -> VirtualNode {
    html! {
        div {
            h1 { "Hello, euv!" }
        }
    }
}

// mount internally:
// 1. Finds #app element via web-sys
// 2. Calls app() to get VirtualNode tree
// 3. Creates DOM elements
// 4. Inserts them into #app
mount("#app", app);

Incremental Rendering

When a signal changes, euv's renderer performs an incremental diff:

let count: Signal<i32> = use_signal(|| 0);

html! {
    div {
        // This becomes a DynamicNode that re-renders when count changes
        span { count }
    }
}

The renderer compares the old and new virtual DOM trees, computing the minimal set of changes needed:

Same tag → Patch only changed attributes and children
Different tag → Replace the entire DOM node
Same text → Skip the update entirely

Keyed Diffing

For list rendering, euv supports keyed diffing to efficiently handle reordering:

struct Item {
    id: String,
    name: String,
}

html! {
    ul {
        for item in { items.get() } {
            li {
                key: item.id
                item.name
            }
        }
    }
}

When all children have a key attribute, the renderer uses a key-based diff algorithm that can reuse existing DOM nodes even when the list order changes. Without keys, it falls back to positional diffing (comparing by index).

Event Delegation

euv's renderer uses global event delegation for bubbling events. Instead of attaching individual event listeners to each element, it registers a single listener on window and dispatches events based on the element's ID:

html! {
    button {
        onclick: move |event: Event| {
            // This handler is stored in a global registry
            // and dispatched by the window-level listener
        }
        "Click me"
    }
}

This dramatically reduces the number of DOM event listeners, improving both memory usage and performance.

Performance Characteristics

Why WASM is Fast

WebAssembly offers several performance advantages over JavaScript:

Near-native speed — WASM instructions map closely to native CPU instructions
No parsing overhead — WASM is a binary format that doesn't need parsing like JavaScript
No GC pauses — Rust's ownership model means no garbage collection
Predictable performance — No JIT warmup or deoptimization

Virtual DOM Diffing Performance

euv's virtual DOM diffing happens entirely in WASM memory, which offers several advantages:

// The diff computation is a pure Rust function
// No JavaScript round-trips during diffing
fn diff(old: &VirtualNode, new: &VirtualNode) -> PatchSet {
    // ... comparison logic ...
}

The only JavaScript interaction happens when patches are applied to the real DOM (via web-sys).

Rendering Optimization

euv includes an important optimization: when a DynamicNode re-renders, the renderer compares the new virtual DOM output with the old one. If they're identical, the DOM patch is skipped entirely:

let count: Signal<i32> = use_signal(|| 0);

html! {
    div {
        // DynamicNode re-renders when count changes
        span { { format!("Count: {}", count.get()) } }
        // But if the formatted string hasn't changed,
        // the DOM update is skipped
    }
}

This is particularly effective for scenarios where signals update frequently but the rendered output doesn't change (e.g., a timer signal that updates every second but the display only shows minutes).

Batch Updates

The batch function groups multiple signal updates into a single DOM update:

use euv::*;

// Multiple set() calls within a batch are coalesced
batch(|| {
    signal1.set(value1);
    signal2.set(value2);
    signal3.set(value3);
});
// Only one DOM update happens after the batch

The watch! macro also uses batching internally:

let celsius: Signal<f64> = use_signal(|| 0.0);
let fahrenheit: Signal<f64> = use_signal(|| 32.0);

watch!(celsius, |celsius_value: f64| {
    fahrenheit.set(celsius_value * 9.0 / 5.0 + 32.0);
});

watch!(fahrenheit, |fahrenheit_value: f64| {
    celsius.set((fahrenheit_value - 32.0) * 5.0 / 9.0);
});

When two signals watch each other, the batch mechanism ensures that cascading set calls within the same frame are merged into a single DOM update, preventing intermediate state flicker.

The Runtime Architecture

Hook System

euv's hook system manages the lifecycle of reactive primitives within dynamic nodes. Each DynamicNode has an associated HookContext that stores:

Signal subscriptions
Cleanup callbacks
Interval handles
Window event listeners

fn timer_tab() -> VirtualNode {
    let elapsed: Signal<i32> = use_signal(|| 0);
    let running: Signal<bool> = use_signal(|| false);
    let handle: Signal<Option<IntervalHandle>> = use_signal(|| None);

    // Register a cleanup callback
    use_cleanup(move || {
        if let Some(h) = handle.get() {
            h.clear();
        }
    });

    // Use watch! to react to signal changes
    watch!(running, |is_running: bool| {
        if is_running {
            let elapsed_signal: Signal<i32> = elapsed;
            let handle_signal: Signal<Option<IntervalHandle>> = handle;
            let new_handle: IntervalHandle = use_interval(1000, move || {
                let current: i32 = elapsed_signal.get();
                elapsed_signal.set(current + 1);
            });
            handle_signal.set(Some(new_handle));
        } else {
            let handle_opt: Option<IntervalHandle> = handle.get();
            if let Some(existing_handle) = handle_opt {
                existing_handle.clear();
            }
            handle.set(None);
        }
    });

    html! {
        div {
            span { { format_time(elapsed.get()) } }
            if { !running.get() } {
                button {
                    onclick: move |_event: Event| { running.set(true); }
                    "Start"
                }
            } else {
                button {
                    onclick: move |_event: Event| { running.set(false); }
                    "Pause"
                }
            }
        }
    }
}

Component Lifecycle

Components in euv are functions that return VirtualNode. The #[component] attribute macro marks them for the html! macro to recognize:

use euv::*;

#[derive(Clone, Default)]
struct MyCardProps {
    title: &'static str,
}

#[component]
pub fn my_card(node: VirtualNode<MyCardProps>) -> VirtualNode {
    let MyCardProps { title, .. }: MyCardProps = node.try_get_props().unwrap_or_default();
    let children: VirtualNode = node.try_get_child_node();
    html! {
        div {
            class: c_card()
            h3 {
                class: c_card_title()
                title
            }
            children
        }
    }
}

The component lifecycle is managed through the virtual DOM:

Creation — When a component tag is encountered in html!, the component function is called
Update — When a parent re-renders, the component function is called again with new props
Cleanup — When a component is removed from the DOM, its associated hooks are cleaned up

The Keep-Alive Pattern

In euv, using match or if/else to switch components destroys the old branch and creates a new one. The Keep-Alive pattern uses CSS display: none/block to preserve component state:

let tab: Signal<String> = use_signal(|| "counter".to_string());

html! {
    div {
        // Tab bar
        div {
            class: c_tab_bar()
            div {
                class: if { tab.get() == "counter" } { c_tab_item_active() } else { c_tab_item_inactive() }
                onclick: move |_event: Event| { tab.set("counter".to_string()); }
                "Counter"
            }
            div {
                class: if { tab.get() == "form" } { c_tab_item_active() } else { c_tab_item_inactive() }
                onclick: move |_event: Event| { tab.set("form".to_string()); }
                "Form"
            }
        }
        // Render all tabs simultaneously, control visibility with display
        div {
            style: { display: if { tab.get() == "counter" } { "block".to_string() } else { "none".to_string() }; }
            { counter_tab() }
        }
        div {
            style: { display: if { tab.get() == "form" } { "block".to_string() } else { "none".to_string() }; }
            { form_tab() }
        }
    }
}

This keeps all DynamicNode instances and their HookContext alive — signals retain values, setInterval continues running, and form inputs preserve their state.

Working with JavaScript from WASM

The js-sys Bridge

When euv needs to interact with JavaScript (e.g., making HTTP requests), it goes through js-sys:

use euv::*;

// fetch is a JavaScript API accessed through js-sys/web-sys
let window: Window = window().expect("no global window exists");
let promise: Promise = window.fetch_with_str("https://httpbin.org/get");
let future: JsFuture = JsFuture::from(promise);

The web-sys Bridge

For browser APIs, euv uses web-sys:

use euv::*;

let win: Window = window().expect("no global window exists");
let location: Location = win.location();
let hash: String = location.hash().unwrap_or_default();
let _ = location.set_hash("#/about");

Type Conversion

Crossing the WASM boundary requires type conversion. euv handles this automatically through several traits:

// IntoNode trait - converts Rust types to VirtualNode
// String, &str, i32, bool, Signal<T>, etc. all implement IntoNode

let count: Signal<i32> = use_signal(|| 0);

html! {
    div {
        // count (Signal<i32>) is converted to VirtualNode via IntoNode
        count
        // String is converted via IntoNode
        "Hello"
        // i32 is converted via IntoNode
        42
    }
}

The IntoReactiveValue trait handles attribute value conversion:

// All of these can be used as attribute values:
html! {
    div {
        data_role: "container"           // &str → AttributeValue::Text
        data_id: "12345"                 // &str → AttributeValue::Text
        aria_label: "Demo section"       // &str → AttributeValue::Text
    }
}

Conclusion

euv's use of WebAssembly is not just a compilation target — it's a fundamental design choice that shapes every aspect of the framework:

Memory safety through Rust's ownership model, with no GC overhead
Near-native performance for virtual DOM diffing and signal computations
Efficient event handling through global delegation
Deterministic resource management through the hook system and cleanup callbacks

The WASM compilation pipeline — from Rust source through wasm-bindgen to browser execution — is streamlined by tools like wasm-pack and the euv CLI. The result is a framework that brings the power of Rust's type system and performance to the browser, while maintaining seamless interoperability with the JavaScript ecosystem through js-sys and web-sys.

Understanding the WASM internals helps you write more efficient euv applications. Key takeaways:

Signal cloning is cheap (reference counting, not deep copy)
Virtual DOM diffing happens entirely in WASM memory
Use batch to group signal updates
Use the Keep-Alive pattern to preserve component state across tab switches
All browser APIs are accessible through use euv::* — no need for direct js-sys or web-sys dependencies

Project Code：https://github.com/euv-dev/euv

List Rendering Patterns

tengxgfyrz67s — Sun, 28 Jun 2026 03:29:31 +0000

Project Code：https://github.com/euv-dev/euv

Rendering lists is one of the most common tasks in UI development. euv provides powerful patterns for rendering dynamic lists, from simple iterations to complex keyed lists with reactive updates. This article explores the for loop in the html! macro, keyed diffing, and various list manipulation patterns.

Basic List Rendering with for

The html! macro supports for loops to iterate over collections and render a node for each item:

use euv::*;

fn app() -> VirtualNode {
    let items = vec!["Apple", "Banana", "Cherry"];

    html! {
        ul {
            for item in items {
                li { item }
            }
        }
    }
}

mount("#app", app);

This iterates over the items vector and renders an <li> element for each string. The for loop in the html! macro works with any iterable expression.

Rendering Lists from Signals

In practice, lists usually come from reactive signals. Use .get() to access the current value of a signal containing a list:

use euv::*;

fn app() -> VirtualNode {
    let items: Signal<Vec<String>> = use_signal(|| {
        vec![
            String::from("Apple"),
            String::from("Banana"),
            String::from("Cherry"),
        ]
    });

    html! {
        ul {
            for item in items.get() {
                li { item }
            }
        }
    }
}

mount("#app", app);

When the items signal changes (e.g., when items are added or removed), euv re-renders the list automatically.

Transforming Lists

You can transform list data before rendering:

use euv::*;

fn app() -> VirtualNode {
    let numbers: Signal<Vec<i32>> = use_signal(|| {
        vec![1, 2, 3, 4, 5]
    });

    html! {
        ul {
            for n in numbers.get() {
                li { "Square: " {n * n} }
            }
        }
    }
}

mount("#app", app);

Lists with Complex Items

Lists can contain complex structures, not just strings:

use euv::*;

fn app() -> VirtualNode {
    let todos: Signal<Vec<(String, bool)>> = use_signal(|| {
        vec![
            (String::from("Learn euv"), true),
            (String::from("Build an app"), false),
            (String::from("Deploy to production"), false),
        ]
    });

    html! {
        ul {
            for (text, done) in todos.get() {
                li {
                    class: class!(
                        "todo-item",
                        if done { "completed" } else { "pending" }
                    ),
                    text
                }
            }
        }
    }
}

mount("#app", app);

Dynamic Lists with Add/Remove

Here's a complete example of a dynamic list where items can be added and removed:

use euv::*;

fn app() -> VirtualNode {
    let items: Signal<Vec<String>> = use_signal(|| {
        vec![String::from("Item 1"), String::from("Item 2")]
    });

    html! {
        div {
            h1 { "Dynamic List" }
            ul {
                for item in items.get() {
                    li {
                        span { item }
                        button {
                            onclick: move || {
                                items.set(vec![
                                    String::from("Item 1"),
                                    String::from("Item 2"),
                                    String::from("Item 3"),
                                ]);
                            }
                            "Add Item"
                        }
                    }
                }
            }
            p { "Total items: " {items.get().len()} }
        }
    }
}

mount("#app", app);

Using Keyed Diffing

euv's renderer employs Keyed Diffing to efficiently update lists. When items in a list have unique identifiers, euv can track individual items across renders, minimizing unnecessary DOM operations. This is particularly important when:

Items are added or removed from the list
Items are reordered
The list is large

To take advantage of keyed diffing, ensure that each item in your list has a stable, unique identifier. The html! macro's for loop automatically works with the diffing algorithm to produce efficient updates.

Lists with Conditional Rendering

You can combine for loops with if expressions for conditional rendering within lists:

use euv::*;

fn app() -> VirtualNode {
    let items: Signal<Vec<(String, bool)>> = use_signal(|| {
        vec![
            (String::from("Public item"), true),
            (String::from("Private item"), false),
            (String::from("Public item 2"), true),
        ]
    });

    html! {
        ul {
            for (name, is_public) in items.get() {
                if is_public {
                    li { name }
                }
            }
        }
    }
}

mount("#app", app);

This renders only the items where is_public is true, filtering out the rest.

Empty List States

Always consider what to display when a list is empty:

use euv::*;

fn app() -> VirtualNode {
    let items: Signal<Vec<String>> = use_signal(|| vec![]);

    html! {
        div {
            if items.get().is_empty() {
                p { "No items yet. Add one to get started!" }
            } else {
                ul {
                    for item in items.get() {
                        li { item }
                    }
                }
            }
        }
    }
}

mount("#app", app);

Nested Lists

Lists can be nested inside other lists for hierarchical data:

use euv::*;

fn app() -> VirtualNode {
    let categories: Signal<Vec<(String, Vec<String>)>> = use_signal(|| {
        vec![
            (String::from("Fruits"), vec![
                String::from("Apple"),
                String::from("Banana"),
            ]),
            (String::from("Vegetables"), vec![
                String::from("Carrot"),
                String::from("Broccoli"),
            ]),
        ]
    });

    html! {
        div {
            for (category, items) in categories.get() {
                div {
                    h2 { category }
                    ul {
                        for item in items {
                            li { item }
                        }
                    }
                }
            }
        }
    }
}

mount("#app", app);

Lists with Interactive Items

Each item in a list can have its own interactive elements:

use euv::*;

fn app() -> VirtualNode {
    let count: Signal<i32> = use_signal(|| 0);

    html! {
        div {
            h1 { "Shopping List" }
            ul {
                for item in vec!["Milk", "Eggs", "Bread"] {
                    li {
                        span { item }
                        button {
                            onclick: move || {
                                count.set(count.get() + 1);
                            }
                            "Add to cart"
                        }
                    }
                }
            }
            p { "Items in cart: " {count} }
        }
    }
}

mount("#app", app);

Combining Lists with Computed Values

Use computed! to derive filtered or sorted versions of lists:

use euv::*;

fn app() -> VirtualNode {
    let all_items: Signal<Vec<i32>> = use_signal(|| {
        vec![5, 3, 8, 1, 9, 2, 7, 4, 6]
    });

    let sorted_items = computed!(all_items, |items| {
        let mut sorted = items.clone();
        sorted.sort();
        sorted
    });

    html! {
        div {
            h1 { "Sorted Numbers" }
            ul {
                for item in sorted_items.get() {
                    li { item }
                }
            }
        }
    }
}

mount("#app", app);

The computed! macro automatically re-sorts whenever all_items changes, keeping the sorted view in sync.

Performance Considerations

When working with large lists, keep these tips in mind:

Use keyed diffing — Ensure items have stable identifiers so euv can efficiently track changes.
Avoid unnecessary signal reads — Reading a signal inside a for loop creates a subscription for each iteration. Consider extracting the value first:

let current_items = items.get();
for item in current_items {
    li { item }
}

Use batch for bulk updates — When making multiple changes to a list, wrap them in a batch call:

batch(|| {
    count.set(1);
});

Keep list items simple — Complex list items with many nested elements increase the diffing workload. Keep the virtual DOM tree shallow where possible.

Summary

euv provides flexible and efficient patterns for rendering lists. The for loop in the html! macro iterates over any collection, while reactive signals keep the UI in sync with data changes. Keyed diffing ensures efficient updates even for large or frequently changing lists. By combining these features with computed!, if expressions, and interactive elements, you can build sophisticated list-based UIs with minimal code.

Project Code：https://github.com/euv-dev/euv

Response Building and Sending in Hyperlane

tengxgfyrz67s — Sun, 28 Jun 2026 03:21:43 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

In the hyperlane framework, response building and sending are core operations that every developer must master. Unlike many web frameworks that abstract these details away, hyperlane gives you fine-grained control over how HTTP responses are constructed and delivered to clients. This article explores the comprehensive API for building responses, setting headers, managing status codes, and efficiently sending data back to clients.

Hyperlane is a lightweight, high-performance, cross-platform Rust HTTP server library built on top of Tokio. Its response system is designed for both simplicity and flexibility, supporting method chaining, attribute macros, and multiple sending strategies.

Setting Response Basics

HTTP Version and Status Code

Every HTTP response starts with a version and a status code. Hyperlane provides a fluent API for setting these fundamental properties:

ctx.get_mut_response().set_version(HttpVersion::Http1_1).set_status_code(200);

This sets the response to HTTP/1.1 with a 200 OK status. The HttpVersion enum supports both HTTP/1.1 and HTTP/1.0, giving you control over protocol negotiation.

Response Body

The response body can be set with a simple string:

ctx.get_mut_response().set_body("Hello World");

This stores the body content internally in the response object. The body is not sent to the client until you explicitly call the build() method and send the resulting data through the stream.

Response Headers

Hyperlane provides two methods for setting response headers:

ctx.get_mut_response().set_header(CONTENT_TYPE, APPLICATION_JSON);
ctx.get_mut_response().add_header(SERVER, "hyperlane");

set_header — Sets a header value, replacing any existing value for the same key.
add_header — Appends a header value, allowing multiple values for the same header key (useful for Set-Cookie headers).

These methods use the HeaderName constants defined in hyperlane's HTTP module, ensuring type safety and preventing typos.

Building the Response

The `build()` Method

The build() method serializes the response into a byte buffer that can be sent over the network:

let data = ctx.get_mut_response().build();

This method takes all the configured properties — version, status code, headers, and body — and produces a complete HTTP response in binary format. The resulting data is ready to be sent through the stream.

It is important to note that build() should be called after all response properties have been configured. Any changes made to the response after calling build() will not be reflected in the already-built data.

Sending the Response

Hyperlane offers multiple strategies for sending response data, each with different trade-offs:

`try_send` — Non-Blocking Send

stream.try_send(data).await;

try_send attempts to send the data without blocking. If the stream's internal buffer is full, it returns an error immediately rather than waiting. This is useful when you want to handle backpressure gracefully:

let data = ctx.get_mut_response().build();
if stream.try_send(data).await.is_err() {
    stream.set_closed(true);
    return Status::Reject;
}

`send` — Blocking Send

stream.send(data).await;

send will wait until the data can be sent, blocking the current task if necessary. Use this when you need guaranteed delivery and can tolerate potential waiting.

`try_send_list` — Batch Sending

stream.try_send_list(&frame_list).await;

For scenarios where you need to send multiple frames at once (such as WebSocket messages or SSE events), try_send_list efficiently sends a collection of data frames in a single operation.

`try_flush` — Flushing the Stream

stream.try_flush().await;

After sending data, calling try_flush ensures that all buffered data is pushed to the underlying socket immediately. This is particularly important for SSE and streaming responses where data needs to reach the client without delay.

Attribute Macros for Response Configuration

Hyperlane's attribute macro system provides a declarative approach to response configuration, making your code more concise and readable.

Setting Status Code and Version

#[response_status_code(200)]
#[response_version(HttpVersion::Http1_1)]
async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
    // Response is automatically configured with 200 OK and HTTP/1.1
    Status::Continue
}

Setting Response Body

#[response_body("Hello World")]
async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
    // The response body is automatically set to "Hello World"
    Status::Continue
}

Setting Response Headers

#[response_header(SERVER => HYPERLANE)]
#[response_header(SET_COOKIE, "session_id=abc123")]
async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
    // Headers are automatically added to the response
    Status::Continue
}

Clearing Response Headers

#[clear_response_headers]
async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
    // All existing response headers are cleared
    Status::Continue
}

Attribute Macros for Sending

Hyperlane also provides attribute macros for the sending phase:

#[try_send]
#[send]
#[try_flush]
#[flush]
#[closed]

These macros can be applied to handler methods to automatically perform the corresponding stream operation after the handler completes. For example, #[try_send] will automatically build and send the response through the stream.

Complete Response Lifecycle Example

Here is a complete example showing the full response lifecycle in a custom middleware:

struct ResponseMiddleware;

impl ServerHook for ResponseMiddleware {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // Step 1: Configure the response
        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200);

        // Step 2: Set the body
        ctx.get_mut_response().set_body("Hello World");

        // Step 3: Add headers
        ctx.get_mut_response().set_header(CONTENT_TYPE, APPLICATION_JSON);
        ctx.get_mut_response().add_header(SERVER, "hyperlane");

        // Step 4: Build the response into bytes
        let data = ctx.get_mut_response().build();

        // Step 5: Send the response, handling potential errors
        if stream.try_send(data).await.is_err() {
            stream.set_closed(true);
            return Status::Reject;
        }

        Status::Continue
    }
}

server.response_middleware::<ResponseMiddleware>();

Combining Response Building with Other Features

Response Building in Route Handlers

Response building integrates seamlessly with route handlers. You can use route parameters and request data to construct dynamic responses:

#[route("/test/{text}")]
struct Route;

impl ServerHook for Route {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let param: String = ctx.get_route_param("text");
        let body = format!("Hello, {}!", param);

        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200)
            .set_body(body);

        let data = ctx.get_mut_response().build();
        stream.try_send(data).await;

        Status::Continue
    }
}

Response Building with Cookies

Response building works hand-in-hand with cookie management. After building a cookie with CookieBuilder, you attach it to the response headers:

let cookie = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();

ctx.get_mut_response().set_header(SET_COOKIE, &cookie);

Response Building with SSE

For Server-Sent Events, the response building process is slightly different. You set the content type to text/event-stream and initialize with an empty body:

let data = ctx.get_mut_response()
    .set_header(CONTENT_TYPE, TEXT_EVENT_STREAM)
    .set_body(Vec::new())
    .build();

stream.try_send(data).await;

for i in 0..10 {
    let body = format!("data:{i}{HTTP_DOUBLE_BR}");
    stream.try_send(&body).await;
}

Best Practices

Always call build() after all properties are configured. Changes made after build() are not reflected in the serialized data.
Use try_send for non-critical responses where you can gracefully handle backpressure. Use send when guaranteed delivery is required.
Prefer attribute macros for simple response configurations to keep your code clean and maintainable.
Handle send errors gracefully. Always check the return value of try_send and close the stream if necessary using stream.set_closed(true).
Flush after sending streaming data. For SSE and long-polling scenarios, call try_flush() to ensure data reaches the client promptly.
Set appropriate headers before building. Remember that the order of header operations matters — set_header replaces while add_header appends.

Conclusion

Hyperlane's response building and sending system provides a powerful and flexible foundation for constructing HTTP responses. Whether you use the fluent method chain API or the declarative attribute macros, you have full control over every aspect of the response lifecycle. The multiple sending strategies — try_send, send, try_send_list, and try_flush — ensure that you can handle everything from simple request-response patterns to complex streaming scenarios with ease.

By mastering these APIs, you can build robust, high-performance web applications that take full advantage of hyperlane's speed and efficiency.

Project Code：https://github.com/hyperlane-dev/hyperlane

HTTP Constants and Types in Hyperlane

tengxgfyrz67s — Sun, 28 Jun 2026 03:13:00 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

Hyperlane provides a comprehensive set of HTTP constants and types that simplify working with HTTP protocols in your Rust applications. Instead of manually specifying MIME types, header names, HTTP versions, and other protocol constants, Hyperlane offers predefined constants that reduce errors and improve code readability. This article covers the key constants and types available in the framework.

Why Use Constants?

When building HTTP servers, you frequently need to specify values like:

Content-Type headers (application/json, text/html)
HTTP versions (HTTP/1.1, HTTP/2)
Header names (SERVER, CONTENT_TYPE, SET_COOKIE)
MIME types (TEXT_EVENT_STREAM, APPLICATION_JSON)

Hardcoding these as string literals is error-prone. A typo like "applicaiton/json" can cause subtle bugs that are hard to trace. Hyperlane's constants eliminate this risk entirely.

Content Type Constants

Hyperlane defines commonly used content type constants:

APPLICATION_JSON — application/json for JSON responses
TEXT_EVENT_STREAM — text/event-stream for SSE responses

Using these constants in your handlers:

ctx.get_mut_response().set_header(CONTENT_TYPE, APPLICATION_JSON);

For SSE responses:

let data = ctx.get_mut_response()
    .set_header(CONTENT_TYPE, TEXT_EVENT_STREAM)
    .set_body(Vec::new())
    .build();
stream.try_send(data).await;

Header Name Constants

Hyperlane provides constants for common HTTP header names:

CONTENT_TYPE — The Content-Type header
SERVER — The Server header
SET_COOKIE — The Set-Cookie header
AUTHORIZATION — The Authorization header
ACCESS_CONTROL_ALLOW_ORIGIN — The Access-Control-Allow-Origin header
ACCESS_CONTROL_ALLOW_METHODS — The Access-Control-Allow-Methods header
ACCESS_CONTROL_ALLOW_HEADERS — The Access-Control-Allow-Headers header

Using these in your code:

ctx.get_mut_response().set_header(CONTENT_TYPE, APPLICATION_JSON);
ctx.get_mut_response().add_header(SERVER, "hyperlane");

CORS Constants

For Cross-Origin Resource Sharing, Hyperlane provides:

WILDCARD_ANY — * for allowing any origin
ALL_METHODS — All HTTP methods for CORS

ctx.get_mut_response()
    .set_header(ACCESS_CONTROL_ALLOW_ORIGIN, WILDCARD_ANY)
    .set_header(ACCESS_CONTROL_ALLOW_METHODS, ALL_METHODS)
    .set_header(ACCESS_CONTROL_ALLOW_HEADERS, WILDCARD_ANY);

HTTP Version Constants

The HttpVersion enum provides type-safe HTTP version specification:

ctx.get_mut_response().set_version(HttpVersion::Http1_1).set_status_code(200);

Using HttpVersion::Http1_1 is both clearer and safer than setting version strings manually.

Route Constants and Types

HTTP Methods

Hyperlane uses the RequestMethod enum for HTTP method matching:

ctx.get_request().get_method() == &RequestMethod::Get

Status Codes

Status codes are set via methods on the response object:

ctx.get_mut_response().set_status_code(200);

WebSocket Types

WebSocketFrame

Hyperlane provides the WebSocketFrame type for working with WebSocket data:

let body_list = WebSocketFrame::create_frame_list(&body);
stream.send_list(body_list).await;

The WebSocketFrame::create_frame_list method serializes message data into a list of frames ready for transmission.

Cookie Types

CookieBuilder

Hyperlane's CookieBuilder provides a fluent API for constructing HTTP cookies:

let cookie = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();
ctx.get_mut_response().set_header(SET_COOKIE, &cookie);

The builder supports chaining multiple configuration calls:

let cookie = CookieBuilder::new("session", "token123")
    .set_expires("Wed, 21 Oct 2025 07:28:00 GMT")
    .set_domain("example.com")
    .set_same_site("Strict")
    .set_max_age(3600)
    .set_path("/")
    .secure()
    .http_only()
    .build();

To clear a cookie:

let clear_cookie = CookieBuilder::new("session", "").set_max_age(0).build();

File Extension Types

Hyperlane provides the FileExtension type for working with file types:

let file_extension = FileExtension::get_extension_name(&file_path);
let content_type = FileExtension::parse(&file_extension).get_content_type();

This automatically maps file extensions to their corresponding MIME types, which is essential for static file serving.

SSE Constants

For Server-Sent Events, Hyperlane provides the HTTP_DOUBLE_BR constant for line endings:

for i in 0..10 {
    let body = format!("data:{i}{HTTP_DOUBLE_BR}");
    stream.try_send(&body).await;
}

The HTTP_DOUBLE_BR constant ensures correct SSE formatting with double line breaks after each event.

Request and Response Types

Server

The central server type:

let mut server: Server = Server::default();

ServerConfig

Configuration type for server-level settings:

let mut config: ServerConfig = ServerConfig::default();
config.set_address("0.0.0.0:80");
config.set_nodelay(Some(true));
config.set_ttl(Some(128));

RequestConfig

Configuration type for request-level settings:

let request_config_json = r#"{
    "buffer_size": 8192,
    "max_path_size": 8192,
    "max_header_count": 100,
    "max_header_key_size": 8192,
    "max_header_value_size": 8192,
    "max_body_size": 2097152,
    "read_timeout_ms": 6000
}"#;
let request_config = RequestConfig::from_json(request_config_json).unwrap();

ServerControlHook

Type for controlling server lifecycle:

let server_control_hook = server.run().await.unwrap_or_default();
server_control_hook.wait().await;

Status Enum

The Status enum is used in middleware to control the processing pipeline:

Status::Continue  // Continue to the next middleware
Status::Reject    // Reject the request

Context Type

The Context type carries all request/response data through the pipeline. It is created per-request and provides access to everything from request data to response configuration.

Stream Type

The Stream type manages the underlying TCP connection. It provides methods for sending data, managing connection state, and handling keep-alive:

stream.try_send(data).await;
stream.send(data).await;
stream.try_send_list(&frame_list).await;
stream.try_flush().await;
stream.set_closed(true);

Status Code Constants Pattern

While Hyperlane doesn't provide named constants for all HTTP status codes, it uses numeric codes with semantic setter methods:

ctx.get_mut_response().set_status_code(200);  // OK
ctx.get_mut_response().set_status_code(401);  // Unauthorized
ctx.get_mut_response().set_status_code(500);  // Internal Server Error
ctx.get_mut_response().set_status_code(504);  // Gateway Timeout

Putting It All Together

Here's an example that demonstrates many of these constants and types working together:

#[route("/api/data")]
struct DataHandler;

impl ServerHook for DataHandler {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // Set response headers using constants
        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200)
            .set_header(CONTENT_TYPE, APPLICATION_JSON)
            .add_header(SERVER, "hyperlane");

        // Set a cookie using CookieBuilder
        let cookie = CookieBuilder::new("session", "token123")
            .set_path("/")
            .http_only()
            .build();
        ctx.get_mut_response().set_header(SET_COOKIE, &cookie);

        // Build and send the response
        let data = ctx.get_mut_response().set_body(r#"{"status":"ok"}"#).build();
        if stream.try_send(data).await.is_err() {
            stream.set_closed(true);
            return Status::Reject;
        }

        Status::Continue
    }
}

Best Practices

Always use constants for header names and content types — Never hardcode "Content-Type" when CONTENT_TYPE is available.
Use HttpVersion enum instead of strings — It's type-safe and prevents version string errors.
Use CookieBuilder for cookies — It handles proper cookie formatting including domain, path, and security flags.
Use FileExtension for content type detection — It automatically maps file extensions to MIME types.
Use WebSocketFrame for WebSocket data — It handles proper frame serialization.

Conclusion

Hyperlane's HTTP constants and types provide a robust, type-safe foundation for working with HTTP protocols in Rust. By using predefined constants for content types, header names, HTTP versions, and more, you can write cleaner, more maintainable code with fewer string-related bugs. Combined with types like CookieBuilder, FileExtension, WebSocketFrame, and the Status enum, Hyperlane gives you everything you need to build production-quality HTTP applications.

Project Code：https://github.com/hyperlane-dev/hyperlane

Middleware System

tengxgfyrz67s — Sun, 21 Jun 2026 00:02:36 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

Middleware is one of the most powerful features of Hyperlane. It allows you to intercept and process requests and responses at various stages of the request lifecycle. Whether you need authentication, logging, CORS headers, or custom request transformation, Hyperlane's middleware system provides a clean and flexible way to implement these cross-cutting concerns.

Understanding the Middleware Architecture

Hyperlane's middleware system is built around the ServerHook trait. A middleware is any type that implements ServerHook, which provides two methods:

new(): Called when a new connection is established. Use this for initialization.
handle(): Called for each request on the connection. This is where your middleware logic lives.

The handle() method returns a Status enum that controls the request flow:

Status::Continue: The request proceeds to the next middleware or route handler.
Status::Reject: The request is rejected and the connection may be closed.

Request Middleware

Request middleware runs before the route handler processes the request. It's ideal for tasks like authentication, request validation, and setting up response defaults.

Here's a basic request middleware that sets default response headers:

struct RequestMiddleware;

impl ServerHook for RequestMiddleware {
    async fn new(stream: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        ctx.get_mut_response()
            .set_version(HttpVersion::Http1_1)
            .set_status_code(200);
        Status::Continue
    }
}

server.request_middleware::<RequestMiddleware>();

In this example, the middleware:

Creates a new instance when a connection is established (new())
Sets the HTTP version to 1.1 and status code to 200 for every request (handle())
Returns Status::Continue to let the request proceed

Response Middleware

Response middleware runs after the route handler has processed the request. It's ideal for tasks like sending the response, adding response headers, and logging.

Here's a basic response middleware that sends the built response:

struct ResponseMiddleware;

impl ServerHook for ResponseMiddleware {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let data: Vec<u8> = ctx.get_mut_response().build();
        if stream.try_send(data).await.is_err() {
            stream.set_closed(true);
            return Status::Reject;
        }
        Status::Continue
    }
}

server.response_middleware::<ResponseMiddleware>();

This middleware:

Builds the response into bytes using ctx.get_mut_response().build()
Sends the response data through the stream
If sending fails, marks the stream as closed and rejects the request

Execution Order

The order in which middleware is registered matters. Request middleware runs in the order it's registered, and response middleware runs in reverse order. You can control the execution order using the attribute macro syntax:

#[request_middleware(1)]
struct RequestMiddleware1;

#[request_middleware(2)]
struct RequestMiddleware2;

#[response_middleware]
struct ResponseMiddleware;

The numeric parameter in #[request_middleware(N)] specifies the execution priority. Lower numbers run first. In this example:

RequestMiddleware1 (priority 1) runs first
RequestMiddleware2 (priority 2) runs second
The route handler processes the request
ResponseMiddleware runs last

Practical Middleware Examples

Authentication Middleware

One of the most common middleware use cases is authentication. Here's an example that checks for an Authorization header:

impl ServerHook for AuthMiddleware {
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let auth_str: String = ctx
            .get_request()
            .try_get_header_back(AUTHORIZATION)
            .unwrap_or_default();

        if auth_str.is_empty() {
            let data: Vec<u8> = ctx
                .get_mut_response()
                .set_status_code(401)
                .set_body("Unauthorized")
                .build();
            if stream.try_send(data).await.is_err() {
                stream.set_closed(true);
            }
            return Status::Reject;
        }

        Status::Continue
    }
}

This middleware:

Extracts the Authorization header from the request
If the header is missing or empty, sends a 401 Unauthorized response
Returns Status::Reject to stop further processing
If the header is present, returns Status::Continue to proceed

CORS Middleware

Cross-Origin Resource Sharing (CORS) is essential for APIs that serve clients from different origins:

ctx.get_mut_response()
    .set_header(ACCESS_CONTROL_ALLOW_ORIGIN, WILDCARD_ANY)
    .set_header(ACCESS_CONTROL_ALLOW_METHODS, ALL_METHODS)
    .set_header(ACCESS_CONTROL_ALLOW_HEADERS, WILDCARD_ANY);

This sets the standard CORS headers:

Access-Control-Allow-Origin: * — Allows requests from any origin
Access-Control-Allow-Methods: * — Allows all HTTP methods
Access-Control-Allow-Headers: * — Allows all request headers

Static Resource Middleware

For serving static files, you can create a middleware that reads files from disk:

let file_path: String = format!("{static_path}{path}");
let file_extension: String = FileExtension::get_extension_name(&file_path);
let content_type: &'static str = FileExtension::parse(&file_extension).get_content_type();
let file_data: String = tokio::fs::read_to_string(&file_path).await.unwrap();
ctx.get_mut_response().set_body(file_data);

This middleware:

Constructs the file path from a static directory and the request path
Determines the file extension
Maps the extension to a content type
Reads the file contents and sets them as the response body

Timeout Middleware

Timeout middleware ensures that long-running requests don't block the server:

spawn(async move {
    timeout(
        Duration::from_millis(100),
        async move {
            new_ctx.get_mut_response()
                .set_status_code(504)
                .set_body("timeout");
        }
    ).await.unwrap();
});

This spawns a task that waits for 100ms and then sets a 504 Gateway Timeout response.

Error Handling Middleware

Hyperlane provides specialized middleware for handling errors and panics:

Request Error Handler

struct RequestErrorHook;

impl ServerHook for RequestErrorHook {
    async fn new(_: &mut Stream, ctx: &mut Context) -> Self {
        let request_error: RequestError = ctx
            .try_get_request_error_data()
            .unwrap_or_default();
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let data: Vec<u8> = ctx
            .get_mut_response()
            .set_status_code(500)
            .set_body("error")
            .build();
        stream.try_send(data).await;
        Status::Continue
    }
}

server.request_error::<RequestErrorHook>();

Task Panic Handler

struct TaskPanicHook;

impl ServerHook for TaskPanicHook {
    async fn new(_: &mut Stream, ctx: &mut Context) -> Self {
        let error: PanicData = ctx
            .try_get_task_panic_data()
            .unwrap_or_default();
        Self
    }

    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let data: Vec<u8> = ctx
            .get_mut_response()
            .set_status_code(500)
            .set_body("panic")
            .build();
        stream.try_send(data).await;
        Status::Continue
    }
}

server.task_panic::<TaskPanicHook>();

These hooks catch errors and panics during request processing and return appropriate error responses instead of crashing the server.

Attribute Macro Middleware Registration

In addition to the programmatic API, you can register middleware using attribute macros:

#[request_middleware(1)]
struct RequestMiddleware1;

#[request_middleware(2)]
struct RequestMiddleware2;

#[response_middleware]
struct ResponseMiddleware;

This declarative approach is cleaner and more maintainable, especially when you have many middleware components. The macros handle the registration automatically.

Middleware Best Practices

Keep middleware focused: Each middleware should handle one concern. Don't try to do everything in a single middleware.
Order matters: Register middleware in the correct order. Authentication should come before authorization, which should come before logging.
Handle errors gracefully: Always handle the case where sending a response fails by checking the result of stream.try_send().
Use Status::Reject wisely: Only reject requests when you've already sent an appropriate error response.
Leverage the new() method: Use the new() method for connection-level initialization rather than doing it in handle() for every request.

Conclusion

Hyperlane's middleware system provides a powerful and flexible way to implement cross-cutting concerns in your web application. The ServerHook trait gives you full control over request and response processing, while the attribute macro system offers a more declarative approach. By combining request middleware, response middleware, and error handlers, you can build robust and maintainable web services.

In the next article, we'll explore Hyperlane's routing system, which determines how incoming requests are matched to their handlers.

Project Code：https://github.com/hyperlane-dev/hyperlane

Request Handling

tengxgfyrz67s — Sat, 20 Jun 2026 23:56:36 +0000

Project Code：https://github.com/hyperlane-dev/hyperlane

Introduction

Handling incoming HTTP requests is at the core of any web server. Hyperlane provides a rich set of tools for extracting data from requests, including headers, query parameters, request body, and route parameters. This article covers all the ways you can access request data in Hyperlane.

Accessing Basic Request Information

Hyperlane's Context object provides methods to access all the fundamental parts of an HTTP request:

let method = ctx.get_request().get_method();
let path = ctx.get_request().get_path();
let host = ctx.get_request().get_host();
let headers = ctx.get_request().get_headers();

These methods return:

get_method() — The HTTP method (GET, POST, PUT, DELETE, etc.)
get_path() — The URL path (e.g., /users/123)
get_host() — The Host header value
get_headers() — All request headers as a collection

Reading the Request Body

Hyperlane supports multiple ways to read the request body, depending on the content type:

As a String

let body = ctx.get_request().get_body_string();

This returns the raw body as a UTF-8 string. It's useful for text-based content types like plain text, HTML, or JSON.

As JSON

let json_body: T = ctx.get_request().get_body_json::<T>();

This deserializes the body as JSON into a type T that implements serde::Deserialize. Replace T with your target type:

#[derive(serde::Deserialize)]
struct TestData {
    name: String,
    age: u32,
}

let json_body: TestData = ctx.get_request().get_body_json::<TestData>();

As Raw Bytes

The body can also be accessed as raw bytes through the request object, which is useful for binary data.

Query Parameters

Query parameters are the key-value pairs that appear after ? in a URL. For example, in /search?q=rust&page=1, the query parameters are q=rust and page=1.

Getting a Single Query Parameter

let query = ctx.get_request().try_get_query("key");

This returns an Option<String>. If the parameter doesn't exist, it returns None.

Getting All Query Parameters

You can also retrieve all query parameters at once using the request object's query methods.

Request Headers

Headers provide additional information about the request, such as content type, authentication tokens, and client capabilities.

Getting a Single Header

let host_value = ctx.get_request().try_get_header_back("HOST");

The try_get_header_back method returns an Option<String> for the specified header name.

Getting All Headers

let headers = ctx.get_request().get_headers();

This returns all headers as a collection that you can iterate over.

Cookie Handling

Cookies are a fundamental part of web applications, used for session management, tracking, and storing user preferences.

Getting All Cookies

let cookies = ctx.get_request().try_get_cookies();

Getting a Single Cookie

let cookie = ctx.get_request().try_get_cookie("session_id");

This returns the value of the cookie named session_id, or None if it doesn't exist.

Attribute Macro Request Handling

Hyperlane's attribute macros provide a declarative way to extract request data. Instead of manually calling getter methods, you can annotate variables with attributes:

Request Body

#[request_body(body)]

This automatically extracts the raw request body into the body variable.

JSON Request Body

#[request_body_json(body: TestData)]

This automatically deserializes the JSON body into a TestData struct.

Request Header

#[request_header(HOST => host_value)]

This extracts the HOST header into the host_value variable.

Try Get Request Header

#[try_get_request_header(HOST => host_value)]

This is the safe version that returns an Option instead of panicking if the header is missing.

Request Path

#[request_path(path)]

This extracts the request path into the path variable.

Query Parameter

#[request_query("key" => query_value)]

This extracts the key query parameter into query_value.

Method Checking

#[is_get_method]

This attribute checks if the request method is GET.

Multiple Methods

#[methods("GET", "POST")]

This checks if the request method matches any of the specified methods.

HTTP Version Checking

#[is_http1_1_version]

This checks if the request uses HTTP/1.1.

WebSocket Upgrade Checking

#[is_ws_upgrade_type]

This checks if the request is a WebSocket upgrade request.

WebSocket Requests

For WebSocket connections, Hyperlane provides special handling:

#[route("/ws_upgrade_type")]
struct Websocket;

impl ServerHook for Websocket {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    #[is_ws_upgrade_type]
    #[try_get_websocket_request(body)]
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        let body_list: Vec<ResponseBody> = WebSocketFrame::create_frame_list(&body);
        stream.send_list(body_list).await;
        Status::Continue
    }
}

The #[try_get_websocket_request(body)] attribute extracts the WebSocket request body, and WebSocketFrame::create_frame_list creates the response frames.

Server-Sent Events (SSE)

Hyperlane supports Server-Sent Events for streaming data to clients:

let data: Vec<u8> = ctx
    .get_mut_response()
    .set_header(CONTENT_TYPE, TEXT_EVENT_STREAM)
    .set_body(Vec::new())
    .build();
stream.try_send(data).await;

for i in 0..10 {
    let body: String = format!("data:{i}{HTTP_DOUBLE_BR}");
    stream.try_send(&body).await;
}

This sets the Content-Type to text/event-stream and sends a series of events to the client.

Connection Management

Hyperlane provides fine-grained control over connection lifecycle:

Closing a Connection

stream.set_closed(true);

Checking Keep-Alive Status

let keep_alive: bool = stream.is_keep_alive(ctx.get_request().is_enable_keep_alive());

Handling Multiple Requests on One Connection (Keep-Alive)

while stream.try_get_http_request().await.is_ok() {
    if !ctx.get_request().is_enable_keep_alive() {
        stream.set_closed(true);
        break;
    }
}

This loop reads multiple requests from the same connection when Keep-Alive is enabled, and closes the connection when it's not.

Context Attributes

Hyperlane's Context supports storing and retrieving custom data during request processing:

Setting an Attribute

ctx.set_attribute("key", "key", "value");

Getting an Attribute

let value: Option<String> = ctx.try_get_attribute("key");

Removing an Attribute

ctx.remove_attribute("key");

Clearing All Attributes

ctx.clear_attribute();

Attribute Macro Support

#[try_get_attribute("key" => value: String)]
#[attribute("key" => value: String)]

These attributes provide a declarative way to work with context attributes.

Complete Request Handling Example

Here's a comprehensive example that demonstrates various request handling techniques:

use hyperlane::*;
use hyperlane_macros::*;

#[route("/api/users/{id}")]
struct UserRoute;

impl ServerHook for UserRoute {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    #[request_path(path)]
    #[request_query("name" => query_value)]
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // Get route parameter
        let id: String = ctx.get_route_param("id");

        // Get request method
        let method = ctx.get_request().get_method();

        // Get request body as string
        let body = ctx.get_request().get_body_string();

        // Get a header
        let host = ctx.get_request().try_get_header_back("HOST").unwrap_or_default();

        // Get a cookie
        let session = ctx.get_request().try_get_cookie("session_id");

        // Process the request...
        let response_body = format!("User ID: {}, Method: {:?}, Host: {}", id, method, host);

        let data: Vec<u8> = ctx
            .get_mut_response()
            .set_status_code(200)
            .set_body(response_body)
            .build();
        stream.try_send(data).await;

        Status::Continue
    }
}

Best Practices

Use attribute macros for cleaner code: They reduce boilerplate and make your handlers more readable.
Handle missing data gracefully: Use try_get_* methods instead of get_* when the data might not be present.
Validate request data early: Check for required parameters and headers at the beginning of your handler.
Use JSON deserialization for structured data: The get_body_json::<T>() method is more robust than manual string parsing.
Manage connection lifecycle properly: Always check Keep-Alive status and close connections when appropriate.

Conclusion

Hyperlane provides a comprehensive set of tools for handling HTTP requests. From basic request information like method and path to advanced features like WebSocket upgrades and SSE, the library covers all the common request handling scenarios. The attribute macro system makes your code more declarative and maintainable, while the programmatic API gives you full control when needed.

In the next article, we'll explore how to build and send HTTP responses, including status codes, headers, and body content.

Project Code：https://github.com/hyperlane-dev/hyperlane

DEV Community: tengxgfyrz67s

Rendering and Performance Optimization in euv

Understanding the Rendering Pipeline

Incremental Rendering

Full Replacement Rendering

Keyed Diffing

Event Delegation

DOM Cleanup

Performance Best Practices

Use Reactive Signals Wisely

Minimize Signal Updates

Leverage watch! for Derived State

Use Keyed Lists

Avoid Unnecessary DOM Depth

Measuring Performance

Conclusion

CSS Variables and Var Macros in euv

Why Dynamic CSS Variables?

The css-vars! Macro

Basic Usage

How It Works

Scoping CSS Variables

The var! Macro: Reactive Variables

Basic Usage

How It Works Internally

Combining css-vars! and var!

Dynamic Theming

Responsive Spacing and Layout

Animation Control with CSS Variables

Custom Keyframe Animations

Integrating with the class! Macro

Practical Examples

Example 1: Dark Mode Toggle

Example 2: User-Configurable Accent Color

Example 3: Progress Bar with Reactive Styling

Summary

Cookie and Session Management in Hyperlane

Introduction

Reading Cookies from Requests

Getting All Cookies

Getting a Specific Cookie

Creating Cookies with CookieBuilder

Basic Cookie Creation

Full Cookie Configuration

Clearing Cookies

Sending Cookies in Responses

Complete Session Management Example

Cookie-Based Authentication Middleware

Session Management Best Practices

Combining Cookies with Other Hyperlane Features

Cookies and Attributes

Cookies and SSE

Conclusion

TypeScript Interoperability in euv

Table of Contents

Understanding the WASM Interop Layer

Calling JavaScript from Rust with js-sys

Working with JavaScript Objects

Working with JavaScript Arrays

Using JSON

Using JavaScript Promises

Accessing Browser APIs with web-sys

Window and Document Access

Navigation and Routing

Local Storage

Making HTTP Requests with fetch

Exposing Rust Functions to TypeScript

Basic Function Export

Exporting Functions with Parameters

Exporting Functions that Return JsValue

Working with JavaScript Promises and Async

Fetching Data Asynchronously

Using spawn_local with Signals

Practical Patterns for TS Interop

Pattern 1: Calling JavaScript Libraries

Pattern 2: Passing Callbacks to JavaScript

Pattern 3: Using web-sys with Event Handlers

Pattern 4: Combining Browser APIs with Reactive Signals

Pattern 5: Persisting State to Local Storage

Conclusion

The `css-vars!` Macro

The `var!` Macro: Reactive Variables

Combining `css-vars!` and `var!`

Integrating with the `class!` Macro