@funduck/connectrpc-fastify 1.0.14 → 1.0.15

package/README.md

@@ -20,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.*
@@ -116,6 +117,70 @@ ConnectRPC.initMiddlewares(fastify, [
 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
@@ -140,5 +205,7 @@ To use context values in controller, retrieve them from `HandlerContext`.
 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.14",
+  "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"
   }
 }