fix: improve rate limiter IP detection with socket.remoteAddress fallback and type declarations

- Add req.socket?.remoteAddress as third fallback in defaultKeyGenerator
  (after req.ip and req.remoteAddress) to bridge the gap between test
  patterns and the actual default implementation
- Add ip?, remoteAddress?, socket?, and rateLimit? to ZeroRequest type
  in common.d.ts so TypeScript users can work with connection-level
  properties without type errors
- Add missing current/reset properties to ctx.rateLimit type to match
  the runtime shape set by the rate-limit middleware
- Add concrete Bun.serve example in README showing how to populate
  req.ip via server.requestIP() before rate limiting
- Add 3 new unit tests validating the socket.remoteAddress fallback
  and priority ordering in defaultKeyGenerator
- Update all documentation references to reflect the expanded fallback
  chain: req.ip || req.remoteAddress || req.socket?.remoteAddress

Author: jkyberneees

README.md

@@ -73,6 +73,32 @@ Bun.serve({
 })
 ```
 
+### Enabling Client IP for Rate Limiting
+
+Bun's standard `Request` object does not expose the client IP address. To enable the default rate limiter key generator (and any middleware that reads `req.ip`), use `server.requestIP()` in the `Bun.serve` fetch handler:
+
+```typescript
+import http from '0http-bun'
+import {createRateLimit} from '0http-bun/lib/middleware'
+
+const {router} = http()
+
+router.use(createRateLimit({windowMs: 15 * 60 * 1000, max: 100}))
+
+router.get('/', () => new Response('Hello World!'))
+
+// Populate req.ip from Bun's server.requestIP before passing to the router
+Bun.serve({
+  port: 3000,
+  fetch(req, server) {
+    req.ip = server.requestIP(req)?.address
+    return router.fetch(req)
+  },
+})
+```
+
+> **Why is this needed?** The Fetch API `Request` type does not include connection-level properties like `ip`. Bun provides client IP via `server.requestIP(req)` in the fetch handler's second argument. Setting `req.ip` before calling `router.fetch` ensures the rate limiter (and other middleware) can identify clients correctly. Without this, the default key generator falls back to unique per-request keys, which effectively disables rate limiting.
+
 ### With TypeScript Types
 
 ```typescript
@@ -357,7 +383,7 @@ router.get('/api/risky', async (req: ZeroRequest) => {
 
 #### **Rate Limiting**
 
-- **Secure Key Generation**: Default key generator uses `req.ip || req.remoteAddress || 'unknown'` — proxy headers are **not trusted** by default
+- **Secure Key Generation**: Default key generator uses `req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown'` — proxy headers are **not trusted** by default
 - **No Store Injection**: Rate limit store is always the constructor-configured instance (no `req.rateLimitStore` override)
 - **Bounded Memory**: Sliding window rate limiter enforces `maxKeys` (default: 10,000) with periodic cleanup
 - **Synchronous Increment**: `MemoryStore.increment` is synchronous to eliminate TOCTOU race conditions
@@ -435,7 +461,8 @@ router.use(
       req: (req) => ({
         method: req.method,
         url: req.url,
-        ip: req.ip || req.remoteAddress || 'unknown',
+        ip:
+          req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown',
         userAgent: req.headers.get('user-agent'),
       }),
     },

common.d.ts

@@ -20,6 +20,19 @@ export interface ParsedFile {
 export type ZeroRequest = Request & {
   params: Record<string, string>
   query: Record<string, string>
+  // Connection-level IP address (set via Bun.serve's server.requestIP or upstream middleware)
+  ip?: string
+  remoteAddress?: string
+  socket?: {
+    remoteAddress?: string
+  }
+  // Rate limit info (set by rate-limit middleware)
+  rateLimit?: {
+    limit: number
+    remaining: number
+    current: number
+    reset: Date
+  }
   // Legacy compatibility properties (mirrored from ctx)
   user?: any
   jwt?: {
@@ -43,6 +56,8 @@ export type ZeroRequest = Request & {
       used: number
       remaining: number
       resetTime: Date
+      current: number
+      reset: Date
     }
     body?: any
     files?: Record<string, ParsedFile | ParsedFile[]>

lib/middleware/README.md

@@ -854,7 +854,7 @@ router.use(
     max: 20, // Max requests
     keyGenerator: (req) => {
       // Custom key generation
-      // Default uses: req.ip || req.remoteAddress || 'unknown'
+      // Default uses: req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown'
       // NOTE: Proxy headers are NOT trusted by default. If behind a
       // reverse proxy, you MUST provide a custom keyGenerator:
       return (
@@ -911,7 +911,7 @@ const rateLimitOptions: RateLimitOptions = {
   windowMs: 15 * 60 * 1000, // 15 minutes
   max: 100,
   keyGenerator: (req) => {
-    // Default: req.ip || req.remoteAddress || 'unknown'
+    // Default: req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown'
     // Custom: read from proxy-set header if behind a reverse proxy
     return (
       req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
@@ -952,7 +952,8 @@ router.use(
     windowMs: 60 * 1000, // 1 minute sliding window
     max: 10, // Max 10 requests per minute
     maxKeys: 10000, // Maximum tracked keys (default: 10000) — prevents unbounded memory growth
-    keyGenerator: (req) => req.ip || req.remoteAddress || 'unknown',
+    keyGenerator: (req) =>
+      req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown',
   }),
 )
 ```
@@ -1014,7 +1015,8 @@ router.use(
   createSlidingWindowRateLimit({
     windowMs: 3600 * 1000, // 1 hour
     max: 3, // 3 accounts per IP per hour
-    keyGenerator: (req) => req.ip || req.remoteAddress || 'unknown',
+    keyGenerator: (req) =>
+      req.ip || req.remoteAddress || req.socket?.remoteAddress || 'unknown',
   }),
 )
 

lib/middleware/rate-limit.js

@@ -173,6 +173,7 @@ function createRateLimit(options = {}) {
 
 /**
  * Default key generator - uses connection-level IP address
+ * Checks req.ip, req.remoteAddress, and req.socket?.remoteAddress in order.
  * NOTE: If behind a reverse proxy, provide a custom keyGenerator that
  * reads the appropriate header after configuring your proxy to set it.
  * @param {Request} req - Request object
@@ -181,8 +182,8 @@ function createRateLimit(options = {}) {
 let _unknownKeyWarned = false
 
 function defaultKeyGenerator(req) {
-  // Use connection-level IP if available (set by Bun's server)
-  const ip = req.ip || req.remoteAddress
+  // Use connection-level IP if available (set by Bun's server or upstream middleware)
+  const ip = req.ip || req.remoteAddress || req.socket?.remoteAddress
   if (ip) return ip
 
   // I-1: Generate unique key per request to avoid shared bucket DoS

test-types.ts

@@ -122,6 +122,20 @@ const testRequestTypes = async (req: ZeroRequest): Promise<Response> => {
   const params: Record<string, string> = req.params
   const query: Record<string, string> = req.query
 
+  // Test connection-level IP properties
+  const ip: string | undefined = req.ip
+  const remoteAddress: string | undefined = req.remoteAddress
+  const socketAddress: string | undefined = req.socket?.remoteAddress
+
+  // Test top-level rate limit info (set by rate-limit middleware)
+  const topLevelRateLimit = req.rateLimit
+  if (topLevelRateLimit) {
+    const limit: number = topLevelRateLimit.limit
+    const remaining: number = topLevelRateLimit.remaining
+    const current: number = topLevelRateLimit.current
+    const reset: Date = topLevelRateLimit.reset
+  }
+
   // Test context object
   const ctx = req.ctx
   const log = ctx?.log

test/unit/rate-limit.test.js

@@ -501,6 +501,38 @@ describe('Rate Limit Middleware', () => {
       expect(key).toBe('5.6.7.8')
     })
 
+    it('should use req.socket.remoteAddress as last IP fallback', () => {
+      const testReq = {
+        socket: {remoteAddress: '10.0.0.1'},
+        headers: new Headers([['x-forwarded-for', '13.14.15.16']]),
+      }
+
+      const key = defaultKeyGenerator(testReq)
+      expect(key).toBe('10.0.0.1')
+    })
+
+    it('should prefer req.ip over req.socket.remoteAddress', () => {
+      const testReq = {
+        ip: '1.2.3.4',
+        socket: {remoteAddress: '10.0.0.1'},
+        headers: new Headers(),
+      }
+
+      const key = defaultKeyGenerator(testReq)
+      expect(key).toBe('1.2.3.4')
+    })
+
+    it('should prefer req.remoteAddress over req.socket.remoteAddress', () => {
+      const testReq = {
+        remoteAddress: '5.6.7.8',
+        socket: {remoteAddress: '10.0.0.1'},
+        headers: new Headers(),
+      }
+
+      const key = defaultKeyGenerator(testReq)
+      expect(key).toBe('5.6.7.8')
+    })
+
     it('should not trust proxy headers by default', () => {
       const testReq = {
         headers: new Headers([['x-forwarded-for', '9.10.11.12, 13.14.15.16']]),