Provide a way to access the HTTP request in procedures

[angeloashmore]

Is your feature request related to a problem? Please describe.

r19 assumes procedures are written without HTTP requests in mind. Procedures should be usable locally and remotely in the same way.

In most cases, this methodology works. However, some data can only be accessed in an HTTP request, such as HttpOnly cookies. A browser is unable to read HttpOnly cookies to pass to a procedure call.

Describe the solution you'd like

We can provide a getContext() helper that may or may not return HTTP request metadata depending on if the procedure was called via an HTTP request. This forces procedures to handle cases where procedures are called outside r19.

import { createRPCMiddleware, getContext } from "r19";

export const middleware = createRPCMiddleware({
	procedures: {
		whoAmI: (): string | undefined => {
			const context = getContext();

			if (context) {
				return context.cookies.whoAmI;
			}

			return undefined;
		},
	},
});

Describe alternatives you've considered

Context as an argument

A context object could be passed to procedures as the last argument, but that changes the signature of procedures that were written outside r19.

Procedures should be vanilla JavaScript functions with as little influence from r19 as possible.

import { createRPCMiddleware } from "r19";

export const middleware = createRPCMiddleware({
	procedures: {
		whoAmI: (context): string | undefined => {
			return context.cookies.whoAmI;
		},
	},
});

useRequest()

The raw HTTP request could be returned using a helper like useRequest(). This is theoretically simpler, but depending on the server, could return different objects.

For example, Express would return an Express req while Fastify would return a Fastify Request. The difference in return values makes procedures less portable since they become coupled to the server's request type.

Providing a normalized object helps developers write cleaner, more universal procedures.

Additional context

Raised by @asyarb