[Feature]: Native Rust Middlewares for Kito

[nehu3n]

Summary

Add support for native Rust middlewares that can be loaded dynamically at startup and executed directly inside Kito’s core, before any TypeScript middleware.
The idea is to allow anyone to write high-performance middleware as independent Rust crates. When compiled, these crates automatically generate a small npm package that acts as a descriptor used by the JS runtime to register the middleware into the Rust core.

Motivation

Right now, all middleware must be implemented in TypeScript, which:

• limits performance in the hottest part of the pipeline,
• makes it harder to implement heavy or low-level logic efficiently,
• prevents community developers from creating proper native extensions,
• and forces the core to keep growing instead of letting features live as external plugins.

With this feature, Kito gains a native plugin architecture, enabling:

• pure Rust execution for critical middleware,
• dynamic loading of third-party native extensions,
• clean integration through npm,
• real extensibility without recompiling the core,
• and maximal performance with Tokio + Hyper + Kito’s runtime

Proposed Solution

1. Third-party crates

Any developer will be able to create a Rust crate that implements the Middleware trait from kitojs.

A macro like #[export] will:

• generate the required extern "C" functions to expose the middleware,
• handle JSON serialization/deserialization for the middleware options,
• and produce an npm descriptor package at build time through a build script.

2. npm descriptor package

The build script will generate a minimal npm package containing:

• a package.json with metadata and "kito.native": true,
• the path to the generated .so/.dll/.dylib,
• a small index.js file exporting a simple descriptor object.

This descriptor is what the TS runtime of Kito consumes.

3. Registration at startup

Whenever someone does:

app.use(cors({ origin: "*" }));

Kito’s JS runtime detects that it’s a native middleware and calls a N-API function in the core:

register_native_middleware(descriptor)

The call provides:

• the route (or global usage),
• middleware options as JSON,
• the path to the cdylib,
• the middleware’s name and version.

4. Dynamic loading

The Rust core uses libloading to:

• load the cdylib dynamically,
• fetch the exported kito_new_middleware function,
• instantiate the middleware,
• store it inside a global structure like:

DashMap<Route, Vec<MiddlewareEntry>>

Each MiddlewareEntry contains:

• the instantiated middleware,
• the function pointer to handle,
• metadata,
• and information about whether it’s global or route-specific.

5. Pipeline execution

For each request:

1. The core gathers global + route-specific middlewares.
2. Native middlewares run first.
3. If none of them terminate the request, JS middlewares run next.

4. Finally, the JS route handler runs.

Native middlewares receive the usual Context, can modify it, call next, or finish the response early.

Checklist

• I've searched for related issues
• I've read the documentation

[mindplay-dk]

Do you think it's necessary to put the middleware itself in Rust?

It might make more sense to identify specific "high overhead" features and operations that cause projects to be slow, e.g. parsing, encoding, decoding, etc. - anything the operates byte-for-byte on buffers or streams.

If you make the "hot spot" features available as simple functions, and leave the middleware itself to handle logic and just call out to optimized helper functions to do the heavy lifting, the difference vs full Rust middleware would likely be very marginal.

It would make the middleware itself more amenable to contributions, since there is a much larger community of Typescript developers than there are Rust developers. In the same sense, it would make the project more transparent and auditable to Typescript developers.

Also, a library of optimized "heavy lifting" functions creates more opportunities for custom, third-party Typescript middleware - if I have to write custom middleware for a project, and need to parse a form post or something, the helpers would be there.

Alternatively, you might consider providing more "minimal" Rust middleware, e.g. a middleware that provides a parsed body via Context - and then the actual logic could be located in middleware that accesses the "hard work" from Context.

From a personal point of view, however, I think I'd prefer functions, as these tend to more compose more clearly and natural than "middleware that depends on prior middleware". I know this is a popular pattern in Express, but it seems people often choose this more because of "vibes" than anything anything - turning everything into middleware might feel right, but it is often just unnecessary complexity; an arguably more fragile form of composition than simply calling or passing functions. 😊

[nehu3n]

Hi @mindplay-dk ! Adding small high-performance helpers in Rust is definitely useful, but there’s an important limitation:

Under heavy load, N-API calls introduce noticeable overhead. Even if parsing or similar tasks benefit from Rust, the constant value conversions between JavaScript and Rust often cancel out much of that gain.

One of Kito’s main goals is to avoid that overhead entirely. Native middleware stays fully in Rust and never crosses the JS boundary at runtime.

This has a big upside: it lets us use the whole Rust ecosystem naturally from TypeScript. Middleware can tap into everything Rust offers — low-level features, advanced libraries, and high-performance tooling. It opens the door to capabilities that go far beyond what’s practical in pure TypeScript, without adding runtime cost for HTTP (and later WebSockets). Kito becomes a clean, type-safe interface to those lower-level features.

You’re right that this means not everything is as approachable to pure TypeScript developers. But the JavaScript ecosystem has gained a large and active Rust community in recent years, so the balance is shifting.

As for adding something like @kitojs/utils, I’m open to exploring it. I’m not sure yet what would be worthwhile beyond parsing/encoding helpers, so if you have ideas feel free to open an issue. It’s a good direction!

Thanks a lot! 😁

[mindplay-dk]

One of Kito’s main goals is to avoid that overhead entirely. Native middleware stays fully in Rust and never crosses the JS boundary at runtime.

I've been giving this a lot of thought over the past 3-4 days... 🤔

Are you sure you aren't over estimating the overhead of crossing this boundary for one or two API calls in a middleware?

Or perhaps over estimating the potential savings by moving the most essential middleware to Rust?

The thing is, most of the essential middleware that I'm talking about isn't computationally intensive - it doesn't operate on large buffers, doesn't require any complex logic, etc.

You might have seen the post I created here:

#22

Just thinking about the practical implications of each of these:

• CORS header management really just means computing/setting some default headers - the header model will need to exist on the JS side either way, right? so there's a good chance doing this on the Rust side will mean more communication overhead.

• Logging usually requires a logger backend of some sort - these will mostly be NPM JS packages, so you might end up adding more overhead by sending log entries from Rust to Node as well.

• Input Validation: this is nice to have e.g. for middleware to be able to perform efficient input validation - but many (most?) projects by now, in practice, will most likely need/want a standard-schema lib they can use on the frontend as well.

• Error handling: is customized in various ways, at least for production, in most projects, and often needs to integrate with JS based error loggers like Sentry etc. - this is almost inevitably JS bound.

• Authentication: most projects will likely use passport (for some reason) or need to write their own - the logic here is often database bound, and the DB client will almost inevitably be on the JS side.

• Session and cookie management: the only real overhead here is calls to encode/decode or hash/checksum payloads - and these are all generally standard algos that are already available in Node and perform very well. The rest is trivial logic.

• Compression: this would actually be a counter example to my point - compression requires a lot of byte-level work and should probably be performed on the Rust side, where it can be tightly integrated and deeply optimized. It rarely changes, and most users wouldn't know how to contribute any changes here anyway.

• Rate Limiting: I'm unsure about this one. While the logic itself is trivial, persistence is where some of the solutions tend to get pretty complicated. Might be a good candidate for Rust as well.

I think some of these are good candidates for native middleware, but most of them may not be - there's an infinite variety of things we might need/want to do with sessions, cookies, authentication, etc. which are often unique to a project. If I'm working on a TS or JS team, personally, I'd want the important parts of these to be written in the project's language.

In terms of performance, I'm not convinced that most middleware really benefits substantially from outsourcing to Rust? I'm afraid the only place you would see a difference, for a lot of these, is in synthetic benchmarks, with very marginal numbers, perhaps almost immeasurable in the "big picture", e.g. for a typical route that does even the smallest meaningful workload I can imagine, like a single PK query on a local SQLite file.

I understand you have a fairly clear direction with this project - I'm just saying, don't get too hung up on benchmarks and work yourself into a pulp over things that ultimately might not matter.

Just my perspective. 😅

I hope my comments are respectful, and I understand this is just my opinion and personal experience - I only comment because I already like where this project is going, and I want you to succeed. 😉