@funduck/connectrpc-fastify 1.0.13 → 1.0.15

package/README.md

@@ -5,12 +5,10 @@ Code is not production ready.
 
 ## Description
 
-This is a wrapper for [Connectrpc](https://github.com/connectrpc/connect-es) using the [Fastify](https://github.com/fastify/fastify) server.
-
+This is a wrapper for [Connectrpc](https://github.com/connectrpc/connect-es) using the [Fastify](https://github.com/fastify/fastify) server.  
 If you are comfortable with HTTP/1 only and want a compact, ready-to-use setup, this repository is for you.
 
-It simplifies the binding of controllers and middlewares.
-
+It simplifies the binding of controllers and middlewares.  
 I use it as a basis for integration into Nestjs, which will be implemented [here](https://github.com/funduck/connectrpc-fastify-nestjs).
 
 
@@ -22,6 +20,7 @@ This library allows you to:
 * Perform RPC with streaming responses
 * Perform RPC with streaming requests
 * Use middlewares with Fastify hooks
+* Use interceptors for RPC-level request/response handling
 * Access HandlerContext in controllers (headers, context values, etc.)
 
 *Bidirectional streaming RPC is currently out of scope because it requires HTTP/2, which is unstable on public networks. In practice, HTTP/1 provides more consistent performance.*
@@ -32,7 +31,7 @@ You can check out `test` directory for a complete example of server and client.
 ### Controllers
 Controller must implement the service interface and register itself with `ConnectRPC.registerController` in the constructor.
 
-Controller methods receive `HandlerContext` which provides access to request headers, context values, and other metadata.
+Controller methods receive original Connectrpc's `HandlerContext` which provides access to request headers, context values, and other metadata.
 
 ```TS
 import type { HandlerContext } from '@connectrpc/connect';
@@ -75,7 +74,7 @@ try {
 ```
 
 ### Middlewares
-Middlewares run as Fastify hooks and have access to raw request/response objects.
+Middlewares run as Fastify hooks and have access to raw request/response objects and context values which can be retrieved using `getCustomContextValues` helper.
 
 Middleware must implement `Middleware` interface and register itself with `ConnectRPC.registerMiddleware` in the constructor.
 ```TS
@@ -97,7 +96,10 @@ export class AuthMiddleware implements Middleware {
 }
 ```
 
-Create an instance of the middleware before registering the ConnectRPC plugin.
+Create an instance of the middleware before registering the ConnectRPC plugin.  
+And then initialize middlewares using `ConnectRPC.initMiddlewares` method.  
+You can configure middleware to run globally for all services and methods, for specific service only, or for specific method only.  
+For type safety use `middlewareConfig` helper.
 ```TS
 const fastify = Fastify({ logger: true });
 
@@ -107,13 +109,103 @@ new AuthMiddleware();
 await ConnectRPC.registerFastifyPlugin(fastify);
 
 ConnectRPC.initMiddlewares(fastify, [
-    middlewareConfig(AuthMiddleware), // Global middleware for all services and methods
-    // middlewareConfig(AuthMiddleware, ElizaService), // Middleware for all ElizaService methods
-    // middlewareConfig(AuthMiddleware, ElizaService, ['say']), // Middleware for specific method only
+    middlewareConfig(AuthMiddleware), // Global - for all services and methods
+    // middlewareConfig(AuthMiddleware, ElizaService), // for all ElizaService methods
+    // middlewareConfig(AuthMiddleware, ElizaService, ['say']), // for specific method only
 ]);
 
 await fastify.listen({ port: 3000 });
 ```
 
+### Interceptors
+Interceptors run at the RPC layer and have access to the full request/response context from ConnectRPC. They are executed after middlewares and before the controller method is called.
+
+Interceptor must implement `Interceptor` interface and register itself with `ConnectRPC.registerInterceptor` in the constructor.
+```TS
+import { createContextKey } from '@connectrpc/connect';
+import type { AnyFn, Interceptor } from '@funduck/connectrpc-fastify';
+
+const reqIdKey = createContextKey('');
+
+export class LoggingInterceptor implements Interceptor {
+  constructor() {
+    ConnectRPC.registerInterceptor(this);
+  }
+
+  use(next: AnyFn): AnyFn {
+    return async (req) => {
+      // Access request information
+      console.log(`Method: ${req.method.name}`);
+      console.log(`Service: ${req.service.typeName}`);
+      
+      // Access headers
+      const authHeader = req.header.get('authorization');
+      
+      // Attach custom data to context
+      req.contextValues.set(reqIdKey, crypto.randomUUID());
+      
+      // Continue with the request
+      return await next(req);
+    };
+  }
+}
+```
+
+Create an instance of the interceptor and initialize them using `ConnectRPC.init` method.  
+You can configure interceptors to run globally for all services and methods, for specific service only, or for specific method only.  
+For type safety use `interceptorConfig` helper.
+```TS
+import { interceptorConfig } from '@funduck/connectrpc-fastify';
+
+const fastify = Fastify({ logger: true });
+
+new AuthMiddleware();
+new LoggingInterceptor();
+new ElizaController();
+
+await ConnectRPC.init(fastify, {
+  interceptors: [
+    interceptorConfig(LoggingInterceptor), // Global - for all services and methods
+    // interceptorConfig(LoggingInterceptor, ElizaService), // for all ElizaService methods
+    // interceptorConfig(LoggingInterceptor, ElizaService, ['say']), // for specific method only
+  ],
+  middlewares: [
+    middlewareConfig(AuthMiddleware), // Global middleware
+  ],
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+**Key differences between Middlewares and Interceptors:**
+- **Middlewares** run at the HTTP layer (Fastify hooks) with access to raw HTTP request/response objects
+- **Interceptors** run at the RPC layer with access to parsed ConnectRPC request/response objects, typed method information, and can modify the request/response in the RPC context
+
+## Using Context Values
+This is original `ContextValues`, so you need to create context keys using `createContextKey` helper from Connectrpc.
+```TS
+import { createContextKey } from '@connectrpc/connect';
+
+const authKey = createContextKey(''); // '' as default value
+```
+
+To use context values in middleware, retrieve them using `getCustomContextValues` helper.
+```TS
+import { getCustomContextValues } from '@funduck/connectrpc-fastify';
+
+// In middleware "use" method
+const authHeader = req.headers['authorization'];
+const contextValues = getCustomContextValues(req);
+contextValues.set(authKey, authHeader);
+```
+
+To use context values in controller, retrieve them from `HandlerContext`.
+```TS
+// In controller method
+const authValue = context.values.get(authKey);
+```
+
+**Note:** Context values set in middlewares are automatically available in interceptors and controllers. Interceptors can also access and modify context values using `req.contextValues`.
+
 ## Feedback
 Please use [Discussions](https://github.com/funduck/connectrpc-fastify/discussions) or email me.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funduck/connectrpc-fastify",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "author": "Oleg Milekhin <qlfunduck@gmail.com>",
   "description": "Wrapper for official @connectrpc/connect and fastify. Simplifies configuration, type safe binding to controller, simplifies use of middlewares and guards.",
   "main": "dist/index.js",
@@ -32,6 +32,7 @@
     "prettier-plugin-organize-imports": "^4.3.0",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "reflect-metadata": "^0.2.2"
   }
 }