feat(pino): Logging Plugin (#1191)

Fixes #908

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a Pino-based structured per-request logging plugin with
configurable lifecycle logging, abort handling, ID generation, and
streaming error handling.

* **Documentation**
  * Added a Pino integration guide and new navigation links in the docs.

* **Chores**
* Introduced a new experimental Pino package with package metadata,
README, tsconfig and ignore rules.

* **Tests**
* Added tests covering logger context, plugin behavior, streaming/abort
scenarios, and public exports.

* **Other**
* Broadened utility key typing to accept additional property key types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/.vitepress/config.ts

@@ -153,6 +153,7 @@ export default withMermaid(defineConfig({
             { text: 'Body Limit', link: '/docs/plugins/body-limit' },
             { text: 'Simple CSRF Protection', link: '/docs/plugins/simple-csrf-protection' },
             { text: 'Strict GET method', link: '/docs/plugins/strict-get-method' },
+            { text: 'Logging', link: '/docs/integrations/pino' },
           ],
         },
         {
@@ -190,6 +191,7 @@ export default withMermaid(defineConfig({
             { text: 'Hey API', link: '/docs/integrations/hey-api' },
             { text: 'OpenTelemetry', link: '/docs/integrations/opentelemetry' },
             { text: 'Pinia Colada', link: '/docs/integrations/pinia-colada' },
+            { text: 'Pino', link: '/docs/integrations/pino' },
             { text: 'React SWR', link: '/docs/integrations/react-swr' },
             { text: 'Sentry', link: '/docs/integrations/sentry' },
             { text: 'Tanstack Query', link: '/docs/integrations/tanstack-query' },

apps/content/docs/integrations/pino.md

@@ -0,0 +1,133 @@
+---
+title: Pino Integration
+description: Integrate oRPC with Pino for structured logging and request tracking.
+---
+
+# Pino Integration
+
+[Pino](https://getpino.io/) is a fast and lightweight JSON logger. This guide explains how to integrate oRPC with Pino to add structured logging, request tracking, and error monitoring to your applications.
+
+::: warning
+This guide assumes familiarity with [Pino](https://getpino.io/). Review the official documentation if needed.
+:::
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/experimental-pino@latest pino@latest
+```
+
+```sh [yarn]
+yarn add @orpc/experimental-pino@latest pino@latest
+```
+
+```sh [pnpm]
+pnpm add @orpc/experimental-pino@latest pino@latest
+```
+
+```sh [bun]
+bun add @orpc/experimental-pino@latest pino@latest
+```
+
+```sh [deno]
+deno add npm:@orpc/experimental-pino@latest npm:pino@latest
+```
+
+:::
+
+## Setup
+
+To set up Pino with oRPC, use the `LoggingHandlerPlugin` class. This plugin automatically instruments your handler with structured logging, request tracking, and error monitoring.
+
+```ts
+import { LoggingHandlerPlugin } from '@orpc/experimental-pino'
+import pino from 'pino'
+
+const logger = pino()
+
+const handler = new RPCHandler(router, {
+  plugins: [
+    new LoggingHandlerPlugin({
+      logger, // Custom logger instance
+      generateId: ({ request }) => crypto.randomUUID(), // Custom ID generator
+      logRequestResponse: true, // Log request start/end (disabled by default)
+      logRequestAbort: true, // Log when requests are aborted (disabled by default)
+    }),
+  ],
+})
+```
+
+::: info
+The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc-handler), [OpenAPIHandler](/docs/openapi/openapi-handler), or another custom handler.
+:::
+
+::: tip
+For improved log readability during development, consider using [pino-pretty](https://github.com/pinojs/pino-pretty) to format your logs in a human-friendly way.
+
+```bash
+npm run dev | npx pino-pretty
+```
+
+:::
+
+## Using the Logger in Your Code
+
+You can access the logger from the context object using the `getLogger` function:
+
+```ts
+import { getLogger } from '@orpc/experimental-pino'
+
+const procedure = os.handler(({ context }) => {
+  const logger = getLogger(context) // [!code highlight]
+
+  logger?.info('Processing request')
+  logger?.debug({ userId: 123 }, 'User data')
+
+  return { success: true }
+})
+```
+
+## Providing Custom Logger per Request
+
+You can provide a custom logger instance for specific requests by passing it through the context. This is especially useful when integrating with [pino-http](https://github.com/pinojs/pino-http) for enhanced HTTP logging:
+
+```ts
+import {
+  CONTEXT_LOGGER_SYMBOL,
+  LoggerContext,
+  LoggingHandlerPlugin
+} from '@orpc/experimental-pino'
+
+const logger = pino()
+const httpLogger = pinoHttp({ logger })
+
+interface ORPCContext extends LoggerContext {} // [!code highlight]
+
+const router = {
+  ping: os.$context<ORPCContext>().handler(() => 'pong')
+}
+
+const handler = new RPCHandler(router, {
+  plugins: [
+    new LoggingHandlerPlugin({ logger }), // [!code highlight]
+  ],
+})
+
+const server = createServer(async (req, res) => {
+  httpLogger(req, res)
+
+  const { matched } = await handler.handle(req, res, {
+    prefix: '/api',
+    context: {
+      [CONTEXT_LOGGER_SYMBOL]: req.log, // [!code highlight]
+    },
+  })
+
+  if (!matched) {
+    res.statusCode = 404
+    res.end('Not Found')
+  }
+})
+```

packages/pino/.gitignore

@@ -0,0 +1,29 @@
+# Hidden folders and files
+.*
+!.gitignore
+!.*.example
+
+# Common generated folders
+logs/
+node_modules/
+out/
+dist/
+dist-ssr/
+build/
+coverage/
+temp/
+
+# Common generated files
+*.log
+*.log.*
+*.tsbuildinfo
+*.vitest-temp.json
+vite.config.ts.timestamp-*
+vitest.config.ts.timestamp-*
+
+# Common manual ignore files
+*.local
+*.pem
+
+## Hey API Code gen
+/tests/client/

packages/pino/README.md

@@ -0,0 +1,81 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/experimental-pino">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fexperimental-pino?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+  <a href="https://deepwiki.com/unnoq/orpc">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), SWR, Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/experimental-react-swr](https://www.npmjs.com/package/@orpc/experimental-react-swr): [SWR](https://swr.vercel.app/) integration.
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/experimental-pino`
+
+Integration with [Pino](https://getpino.io/) for structured logging.
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

packages/pino/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@orpc/experimental-pino",
+  "type": "module",
+  "version": "0.0.1",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/pino"
+  },
+  "keywords": [
+    "orpc",
+    "pino"
+  ],
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  },
+  "peerDependencies": {
+    "pino": ">=10.1.0"
+  },
+  "dependencies": {
+    "@orpc/client": "workspace:*",
+    "@orpc/server": "workspace:*",
+    "@orpc/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "pino": "^10.1.0"
+  }
+}

packages/pino/src/context.test.ts

@@ -0,0 +1,10 @@
+import pino from 'pino'
+import { CONTEXT_LOGGER_SYMBOL, getLogger } from './context'
+
+it('getLogger', async () => {
+  expect(getLogger({})).toBeUndefined()
+  expect(getLogger({ something: true })).toBeUndefined()
+
+  const logger = pino()
+  expect(getLogger({ [CONTEXT_LOGGER_SYMBOL]: logger })).toBe(logger)
+})

packages/pino/src/context.ts

@@ -0,0 +1,12 @@
+import type { Logger } from 'pino'
+import { get } from '@orpc/shared'
+
+export const CONTEXT_LOGGER_SYMBOL: unique symbol = Symbol('ORPC_PINO_CONTEXT_LOGGER_SYMBOL')
+
+export interface LoggerContext {
+  [CONTEXT_LOGGER_SYMBOL]?: Logger
+}
+
+export function getLogger(context: object): Logger | undefined {
+  return get(context, [CONTEXT_LOGGER_SYMBOL]) as Logger | undefined
+}