Composable handler / middleware API

[katywings]

Challenge

The core Start fs-based api-routes and middleware API hide away most of h3's API surface and have limited composability. h3 allows the composition of nested h3 instances, each with their own routes and middleware. Currently the user must choose between limited Start API's giving them access to getRequestEvent and native h3 API's without getRequestEvent in the form of:

// @refresh reload
import { createHandler, StartServer } from "@solidjs/start/server";
import { H3 } from "h3";
import { createNitropage } from "nitropage/server";

// Custom h3 app, with full access to h3 APIs
const app = new H3();

// No official access to `getRequestEvent` inside this handler
app.use(createNitropage().handler);

// Nested SolidStart app handler
app.use(
  createHandler(() => <StartServer document={Document} />, handlerOptions)
    .handler,
);

app.use("...something after...");

export default app;

Suggestion A: Provide experimental access to decorateHandler & decorateMiddleware

decorateHandler and decorateMiddleware currently are internal functions used to create and provide the RequestEvent inside the h3 request lifecycle:

solid-start/packages/start/src/server/fetchEvent.ts

Line 32 in a8e5a6d

export const decorateHandler = <T extends EventHandler>(fn: T) =>

. By giving users access, they can manually create getRequestEvent capable h3 handlers and middleware wherever they want - so they can have one uniform way to access request information in their whole app. An already existing example of this in the wild can be found here: https://codeberg.org/nitropage/nitropage/src/commit/f20c45edac7419007fd34e89ae34cf24d04310ac/packages/nitropage/src/lib/server/middleware/index.tsx#L19. The code mentioned (in combination with the code above), structures the app as follow:

• base h3 app
  • Nitropage h3 app
    • Nitropage middleware (RequestEvent via decorateMiddleware)
    • Nitropage specific event handlers (RequestEvent via decorateHandler)
  • SolidStart h3 app
    • Start specific fs routes and middleware (RequestEvent handling built-in)

Suggestion B: Decouple Start from h3

Way more involved, but maybe the better long-term approach is to fully decouple Start from h3 and let the user choose how the RequestEvent is bound to the request objects of the users server framework of choice. By giving them full control over the RequestEvent binding, they can use the same binding for their non-Start handlers/middleware. E.g. (just a very barebones example)

import { Hono } from 'hono'
import { contextStorage, getContext } from 'hono/context-storage'
import { createHandler, createRequestEvent } from "@solidjs/start/server";

const startHandler = createHandler();

const provideRequestEvent = () => {
  const ctx = getContext();
  const event = ctx.get('StartRequestEvent');
  if (event) return event;

  const newEvent = createRequestEvent();
  ctx.set('StartRequestEvent');
  return newEvent
}

const app = new Hono()
app.use(contextStorage());
app.use(async (ctx, next) => {
  const res = await startHandler(ctx.req.raw, {
    // Override Start's default RequestEvent binding
    provideRequestEvent
  });

  if (res) return res;
  await next();
});

export default app

This example even goes one step further and customizes the RequestEvent AsyncContext via: https://hono.dev/docs/middleware/builtin/context-storage