[RFC] Server Middleware & Server Context #5639

GiveMe-A-Name · 2024-04-12T09:48:36Z

GiveMe-A-Name
Apr 12, 2024
Collaborator

Summary

Support server middleware like koa-compose.

Support extend custom code before render & after render.
Support pass context between server middleware and dataLoader

Background

Currently, Modern.js can't give a way to control the render process.
Using middleware, we can extend servers conveniently. But now, modern.js server middleware doesn't like koa-compose , can't do something after render.
On the other hand, we can't pass context to runtime from server middleware. Doing some auth work in middleware is very frequent. But the user can't pass user info to runtime for now.

Detailed Design

Future Flag

To avoid breaking change, we would import a future flag to open this feature

// modern.config.ts
import { defineConfig } from '@modern-js/app-tools';
import { pluginServer } from '@modern-js/plugin-server'

export default defineConfig({
    plugin: [
        pluginServer({
            future: {
                unstable_middleware: true,
            }
        })
    ]
})

Middleware Types

type Context<Env> = {
    req: HonoRequest;
    res: Response;
    error: Error;
    header: (name: string, value: string) => void;
    status: (status: number) => void;
    get: (key: string) => unknown;
    set: (key: string, value: unknown) => void;
    body: (data, init: ResponseInit) => Response;
    text: (data, init: ResponseInit) => Response;
    json: (data, init: ResponseInit) => Response;
    html: (data, init: ResponseInit) => Response;
}

type Next = () => void;

export type Middleware = (ctx: Context, next: Next) -> Promise<void> | void;

// dataLoader
interface DataFunctionArgs<Env extends Record<string,any>> {
  request: Request;
  params: Params;
  context?: {
    get: <Key extends keyof Env>(key: Key) => Env[Key];
    set: <Key extends keyof Env>(key: Key, value: Env[Key]) => void;
  };
}

Examples

Authentication

// shared/index.ts
export type Env = {
    user: User;
}

// server/index.ts
import type { Env } from '@shared/index';

export const middleware: Middleware = async (ctx<Env>, next) => {
    const user = await getUserInfo();
    
    if(!user) {
        return redirect('/login');
    }
    
    ctx.set('user', user);
    
    await next();
}

// loader.data.ts
import type { Env } from '@shared/index'

export const loader = ({ context }: LoaderFunctionArgs<Env>) {
    const user = context.get('user');
}

Log Render Timing

export const middleware: Middleware = async (ctx, next) => {
    const start = Date.now()
   
    await next();
 
    const end = Date.now();
    
    const logger = ctx.get('logger');
    logger.info(`render cost time: ${end - start}`);
}

Affect Response

// server/index.ts

export const middleware: Middleware = [
    async (ctx, next) => {
    
        await next();
        
        const response = ctx.res;
        
        if(response.status === 500) {
            // redirect relaod page, when render failed.
            return redirect('/reload');
        }
        
        await next();
    },
    async (ctx, next) => {
        await next();
        
        const language = await getLangauge();
        
        const response = ctx.res;
        const text = await response.text();
        
        const newText = text.replace('<html>', `<html lang=${language}>`);
        
        const newheader = response.header;
        newheader.set('x-custom-xxx', 'custom value');
        
        ctx.res = new Response(newText, {
            status: response.status,
            header: newheader;
        })
    }
]

Deprecated

We can get a reporter beforehand from data loader

// loader.data.ts
import { reporterCtx } from '@modern-js/runtime'

export const loader = ({ context }: LoaderFunctionArgs<Env>) {
    const reporter = context?.get(reporterCtx);
}

We would support this usage, but would tag this as a deprecated status.
We use context.get('reporter') instead of context.get(reporterCtx)

Conclusion

yimingjfe · 2024-04-12T10:17:46Z

yimingjfe
Apr 12, 2024
Collaborator

Why do we expose HonoRequest instead of Request？What's the role of error?

type Context<Env> = {
    req: HonoRequest;
    res: Response;
    error: Error;
    header: (name: string, value: string) => void;
    status: (status: number) => void;
    get: (key: string) => unknown;
    set: (key: string, value: unknown) => void;
    body: (data, init: ResponseInit) => Response;
    text: (data, init: ResponseInit) => Response;
    json: (data, init: ResponseInit) => Response;
    html: (data, init: ResponseInit) => Response;
}

I'm a little worried about the intrusion of the data loader here, why didn't design the context through the hook API in the end?

interface DataFunctionArgs<Env extends Record<string,any>> {
  request: Request;
  params: Params;
  context?: {
    get: <Key extends keyof Env>(key: Key) => Env[Key];
    set: <Key extends keyof Env>(key: Key, value: Env[Key]) => void;
  };
}

13 replies

GiveMe-A-Name Apr 15, 2024
Collaborator Author

I fully agree with this, so why do we need to expose HonoRequest? why don't we use Request + utils instead?

Yes, I agree with you.

users need to import types from the package, declare types with context

Actually, if we using context.get(LoggerCtx), user need import this ctx from somewhere. so in this hand, there is no different between generics and useContext.
If some we would inject by default, we have some way inject type to dataLoader. like this:

interface DefaultEnv = {
  reporter?: Record<string, any>;
  fetch: typeof fetch;
};

interface LoaderContext<E extends Record<string, any> = {}> {
  get: Get<E & DefaultEnv>;
  set: Set<E & DefaultEnv>;
}

export const loader = (context: LoaderContext) => {
  const fetch = context.get("fetch");
};

I don't fully understand why this issue is related to context.get('logger') API ?

I think it is type system world, why we need import runtime code? we can solve it by generics, why we need use a runtime api useContext<Env>() to extend type system.

yimingjfe Apr 15, 2024
Collaborator

Actually, if we using context.get(LoggerCtx), user need import this ctx from somewhere.

Why doesn't context.get('logger') have this problem? Like this example, the middleware or plugin could be another package, not the framework code, and users need to get the "logger" type from this package and inject the type to generic type:

// plugin or middleware package  third package
// logger
const injectLogger = (ctx, next) => {
	ctx.set('logger', logger)
}

// user code
import { Logger } from 'logger'
export const loader = ({ context }: LoaderFunctionArgs<{ logger: Logger }>) {
    const logger = context.get('logger');
}

import { Logger } from 'logger'
export const middleware: Middleware<{ logger: Logger }> = async (ctx, next) => {
    const logger = context.get('logger');
}

yimingjfe Apr 15, 2024
Collaborator

We will base on HonoMiddleware, but the middleware context can be custom by ourselves.

Is the middleware runner in hono, or plugin-server?

GiveMe-A-Name Apr 16, 2024
Collaborator Author

Is the middleware runner in hono, or plugin-server?

Using middleware runner provided by hono

GiveMe-A-Name Apr 16, 2024
Collaborator Author

I don't fully understand why this issue is related to context.get('logger') API ? Like context.get(LoggerCtx), useContext() can also solve this problem, and using generics?

I prefer use loader.context to payload something, like this context.get('logger') or context.logger
if we use context.get(LoggerCtx), we would import runtime code for types system.
if we use useContext<Env>(), we need import node:async_hook module. I don't sure whether it can work in edge worker platform.

zllkjc · 2024-04-15T03:06:42Z

zllkjc
Apr 15, 2024
Maintainer

Looks Great! And I have some topics to discuss

In this RFC's middleware mode, do we need "Hook" ? seems "afterRender" can be replace, but there is no api can instead "afterMatch", if developer want do something like rewrite. can we just modify req url before "next()"(same as match and render) ?
So after this RFC, we can support middleware in Worker ?
Do we need deprecate "Hook" in modern.js, or has some other hook like nuxt when middleware already exist. Maybe need another RFC to list the user's needs and the best practice.

1 reply

GiveMe-A-Name Apr 15, 2024
Collaborator Author

In this RFC's middleware mode, do we need "Hook" ? seems "afterRender" can be replace, but there is no api can instead "afterMatch", if developer want do something like rewrite. can we just modify req url before "next()"(same as match and render) ?

Yes, in this RFC's middleware design, server middleware can replace server hook. But we focus on middleware in this rfc, the server hook would not be deprecated in this version, maybe next major version.
I see only rewrite api can't replace in middleware, we can't modify req url. Actually I don't think rewrite be need, user maybe use other way to implement.

So after this RFC, we can support middleware in Worker ?

Actually, the server middleware can run in Worker now. But server middleware is support by @modern-js/plugin-server. The major problem is edge worker can't support server plugin system. we would support it in next RFC.

Do we need deprecate "Hook" in modern.js, or has some other hook like nuxt when middleware already exist. Maybe need another RFC to list the user's needs and the best practice.

Yes, I think we can deprecate server Hook in modern.js, user can extend render progress using middleware easier. Other hook like nuxt would extend by server plugin, we will discuss it in other RFC

GiveMe-A-Name · 2024-04-15T07:37:21Z

GiveMe-A-Name
Apr 15, 2024
Collaborator Author

I have a idea, why we can't get something from dataLoader.context, like this:

type LoaderFunctionArgs<C extends Record<string, any> = {}> = {
  context: C;
};

interface Context {
  name: string;
  age: number;
}

const loader = ({ context }: LoaderFunctionArgs<Context>) => {
  const name = context.name;
  const age = context.age;
};

Have any problems like this?

1 reply

GiveMe-A-Name Apr 15, 2024
Collaborator Author

Oops, if we get something from context using ., it seems means something is a attributes in context.
If we use context.get('someThing'), it seems like we get something from context, the context just a accessor.

GiveMe-A-Name · 2024-05-10T03:45:20Z

GiveMe-A-Name
May 10, 2024
Collaborator Author

Conclusion

After discuss, we confirm some design.

So Make a summarize.

Enable new server Middleware

To avoid breaking change, we will appoint file export to open this feature.

// server/index.ts

export unstableMiddleware: UnstableMiddleware[] = [mid1, mid2];

Middleware Types

type UnstableMiddlewareContext<Var> = {
    request: Request;
    response: Response;
    header: (name: string, value: string) => void;
    status: (code: number) => void;
    get: (key: string) => unknown;
    set: (key: string, value: unknown) => void;
    redirect: (location: string, status?: number) => Response;
    body: (data: Body, init?: ResponseInit) => Response;
    html: (
      data: string | Promise<string>,
      init?: ResponseInit,
    ) => Response | Promise<Response>;
}

dataLoader

dataLoader get payload from server middleware by using context.get('s').

See Examples.

// server/index.ts
import type { Env } from '@shared/index';

export const middleware: Middleware = async (ctx<Env>, next) => {
    const user = await getUserInfo();
    
    if(!user) {
        return redirect('/login');
    }
    
    ctx.set('user', user);
    
    await next();
}

// loader.data.ts
import type { Env } from '@shared/index'

export const loader = ({ context }: LoaderFunctionArgs<Env>) {
    const user = context.get('user');
}

dataLoader Types

Ensure dataLoader can extend types by others plugins, we will provide a interface to extend types.

See specific implement.

export interface RequestPayload {
  [key: string]: unknown;
}

interface Get<P extends Record<string, unknown>> {
  <Key extends keyof P>(key: Key): P[Key];
}

interface Set<P extends Record<string, unknown>> {
  <Key extends keyof P>(key: Key, value: P[Key]): void;
}

export type RequestContext<P extends Record<string, unknown> = {}> = {
  get: Get<P & RequestPayload>;
  set: Set<P & RequestPayload>;
};

Deprecated `loaderCtx`

we will recommend using context.get('reporter') instead of context.get(reporterCtx) in dataLoader

So we will tag the reporterCtx as deprecated status

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Server Middleware & Server Context #5639

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 4 comments 15 replies

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

[RFC] Server Middleware & Server Context #5639

GiveMe-A-Name Apr 12, 2024 Collaborator

Summary

Background

Detailed Design

Future Flag

Middleware Types

Examples

Authentication

Log Render Timing

Affect Response

Deprecated

Conclusion

Replies: 4 comments · 15 replies

yimingjfe Apr 12, 2024 Collaborator

GiveMe-A-Name Apr 15, 2024 Collaborator Author

yimingjfe Apr 15, 2024 Collaborator

yimingjfe Apr 15, 2024 Collaborator

GiveMe-A-Name Apr 16, 2024 Collaborator Author

GiveMe-A-Name Apr 16, 2024 Collaborator Author

zllkjc Apr 15, 2024 Maintainer

GiveMe-A-Name Apr 15, 2024 Collaborator Author

GiveMe-A-Name Apr 15, 2024 Collaborator Author

GiveMe-A-Name Apr 15, 2024 Collaborator Author

GiveMe-A-Name May 10, 2024 Collaborator Author

Conclusion

Enable new server Middleware

Middleware Types

dataLoader

dataLoader Types

Deprecated loaderCtx

GiveMe-A-Name
Apr 12, 2024
Collaborator

Replies: 4 comments 15 replies

yimingjfe
Apr 12, 2024
Collaborator

GiveMe-A-Name Apr 15, 2024
Collaborator Author

yimingjfe Apr 15, 2024
Collaborator

yimingjfe Apr 15, 2024
Collaborator

GiveMe-A-Name Apr 16, 2024
Collaborator Author

GiveMe-A-Name Apr 16, 2024
Collaborator Author

zllkjc
Apr 15, 2024
Maintainer

GiveMe-A-Name Apr 15, 2024
Collaborator Author

GiveMe-A-Name
Apr 15, 2024
Collaborator Author

GiveMe-A-Name Apr 15, 2024
Collaborator Author

GiveMe-A-Name
May 10, 2024
Collaborator Author

Deprecated `loaderCtx`