@furystack/rest-service 10.0.28 → 10.1.1

package/src/helpers.ts

@@ -1,10 +1,12 @@
 import type { User } from '@furystack/core'
 import type { Injector } from '@furystack/inject'
-import { HttpAuthenticationSettings } from './http-authentication-settings.js'
 import type { RestApi } from '@furystack/rest'
 import type { ImplementApiOptions } from './api-manager.js'
 import { ApiManager } from './api-manager.js'
+import { HttpAuthenticationSettings } from './http-authentication-settings.js'
 import type { DefaultSession } from './models/default-session.js'
+import type { ProxyOptions } from './proxy-manager.js'
+import { ProxyManager } from './proxy-manager.js'
 import type { StaticServerOptions } from './static-server-manager.js'
 import { StaticServerManager } from './static-server-manager.js'
 
@@ -38,3 +40,72 @@ export const useStaticFiles = (options: { injector: Injector } & StaticServerOpt
   const { injector, ...settings } = options
   return injector.getInstance(StaticServerManager).addStaticSite(settings)
 }
+
+/**
+ * Sets up a proxy server that forwards HTTP requests from a source URL to a target URL.
+ *
+ * The proxy acts as an intermediary, forwarding requests and responses while allowing
+ * transformation of headers, cookies, and paths. It returns 502 Bad Gateway on errors
+ * and emits 'onProxyFailed' events for monitoring.
+ *
+ * WebSocket connections can also be proxied by setting `enableWebsockets: true`, allowing
+ * bidirectional real-time communication through the proxy.
+ *
+ * @param options The settings for the proxy server
+ * @param options.injector The Injector instance
+ * @param options.sourceBaseUrl The base URL path to match for proxying (e.g., '/api', '/old').
+ *                               Can be specified with or without a trailing slash.
+ * @param options.targetBaseUrl The target server URL (must be a valid HTTP/HTTPS URL)
+ * @param options.pathRewrite Optional function to rewrite the path before forwarding.
+ *                            Receives the path after sourceBaseUrl, including leading slash and query string.
+ *                            Example: for 'GET /api/users?active=true' with sourceBaseUrl='/api',
+ *                            pathRewrite receives '/users?active=true'
+ * @param options.sourceHostName The hostname for the source server (optional, defaults to all interfaces)
+ * @param options.sourcePort The port for the source server
+ * @param options.headers Optional function to transform request headers.
+ *                        **Note**: Receives headers AFTER filtering hop-by-hop headers
+ *                        (Connection, Keep-Alive, Transfer-Encoding, Upgrade, etc.) for security
+ *                        and protocol compliance. The proxy automatically adds X-Forwarded-* headers.
+ *                        This transformation applies to both HTTP and WebSocket requests.
+ * @param options.cookies Optional function to transform request cookies (array of cookie strings)
+ * @param options.responseCookies Optional function to transform response Set-Cookie headers
+ * @param options.timeout Optional timeout in milliseconds for proxy requests (default: 30000).
+ *                        If exceeded, the request is aborted and 502 is returned.
+ *                        Applies to both HTTP and WebSocket upgrade requests.
+ * @param options.enableWebsockets Optional flag to enable WebSocket proxying (default: false).
+ *                                 When enabled, WebSocket upgrade requests will be forwarded to the target.
+ * @returns a promise that resolves when the proxy is set up
+ * @example
+ * ```ts
+ * // Basic HTTP proxy with timeout
+ * await useProxy({
+ *   injector,
+ *   sourceBaseUrl: '/api',
+ *   targetBaseUrl: 'https://api.example.com',
+ *   sourcePort: 3000,
+ *   timeout: 5000,
+ * })
+ *
+ * // Proxy with WebSocket support
+ * await useProxy({
+ *   injector,
+ *   sourceBaseUrl: '/ws',
+ *   targetBaseUrl: 'https://ws.example.com',
+ *   sourcePort: 3000,
+ *   enableWebsockets: true,
+ * })
+ *
+ * // Proxy with error monitoring (HTTP and WebSocket)
+ * const proxyManager = injector.getInstance(ProxyManager)
+ * proxyManager.subscribe('onProxyFailed', ({ from, to, error }) => {
+ *   console.error(`HTTP Proxy failed: ${from} -> ${to}`, error)
+ * })
+ * proxyManager.subscribe('onWebSocketProxyFailed', ({ from, to, error }) => {
+ *   console.error(`WebSocket Proxy failed: ${from} -> ${to}`, error)
+ * })
+ * ```
+ */
+export const useProxy = (options: { injector: Injector } & ProxyOptions) => {
+  const { injector, ...settings } = options
+  return injector.getInstance(ProxyManager).addProxy(settings)
+}

package/src/http-proxy-handler.ts

@@ -0,0 +1,215 @@
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'http'
+import { Readable } from 'stream'
+import { HeaderProcessor } from './header-processor.js'
+import { PathProcessor } from './path-processor.js'
+
+export interface HttpProxyOptions {
+  sourceBaseUrl: string
+  targetBaseUrl: string
+  pathRewrite?: (sourcePath: string) => string
+  headers?: (originalHeaders: OutgoingHttpHeaders) => OutgoingHttpHeaders
+  cookies?: (originalCookies: string[]) => string[]
+  responseCookies?: (responseCookies: string[]) => string[]
+  timeout?: number
+  onError?: (error: { from: string; to: string; error: unknown }) => void
+}
+
+/**
+ * Handles HTTP request proxying with streaming support
+ */
+export class HttpProxyHandler {
+  private readonly headerProcessor = new HeaderProcessor()
+  private readonly pathProcessor = new PathProcessor()
+
+  constructor(private readonly options: HttpProxyOptions) {}
+
+  /**
+   * Sets up abort controller and timeout for request cancellation
+   */
+  private setupAbortHandling(
+    req: IncomingMessage,
+    res: ServerResponse,
+    timeoutMs: number,
+  ): { abortController: AbortController; timeoutId: NodeJS.Timeout } {
+    const abortController = new AbortController()
+
+    const abortUpstream = () => {
+      try {
+        abortController.abort()
+      } catch {
+        // Ignore abort errors
+      }
+      // Clean up listeners to prevent memory leaks
+      res.off('close', abortUpstream)
+      req.off('aborted', abortUpstream)
+    }
+
+    res.once('close', abortUpstream)
+    req.once('aborted', abortUpstream)
+
+    const timeoutId = setTimeout(() => abortController.abort(), timeoutMs)
+
+    return { abortController, timeoutId }
+  }
+
+  /**
+   * Extracts Set-Cookie headers from the response, handling both standard and undici formats
+   */
+  private extractSetCookieHeaders(proxyResponse: Response): string[] {
+    const setCookieHeaders: string[] = []
+    const anyHeaders = proxyResponse.headers as unknown as { getSetCookie?: () => string[] }
+    const fromGetter = anyHeaders.getSetCookie?.()
+
+    if (fromGetter && Array.isArray(fromGetter) && fromGetter.length) {
+      setCookieHeaders.push(...fromGetter)
+    } else {
+      proxyResponse.headers.forEach((value, key) => {
+        if (key.toLowerCase() === 'set-cookie') {
+          setCookieHeaders.push(value)
+        }
+      })
+    }
+
+    return setCookieHeaders
+  }
+
+  /**
+   * Copies response headers from proxy response to client response
+   */
+  private copyResponseHeaders(proxyResponse: Response, res: ServerResponse): void {
+    proxyResponse.headers.forEach((value, key) => {
+      if (!this.headerProcessor.isHopByHopHeader(key)) {
+        if (key.toLowerCase() !== 'set-cookie') {
+          res.setHeader(key, value)
+        }
+      }
+    })
+  }
+
+  /**
+   * Handles Set-Cookie headers with optional transformation
+   */
+  private handleSetCookieHeaders(setCookieHeaders: string[], res: ServerResponse): void {
+    if (setCookieHeaders.length > 0) {
+      const finalSetCookies = this.options.responseCookies
+        ? this.options.responseCookies(setCookieHeaders)
+        : setCookieHeaders
+      res.setHeader('set-cookie', finalSetCookies)
+    }
+  }
+
+  /**
+   * Streams the response body from proxy to client
+   */
+  private async streamResponseBody(proxyResponse: Response, res: ServerResponse): Promise<void> {
+    if (!proxyResponse.body) {
+      res.end()
+      return
+    }
+
+    const reader = proxyResponse.body.getReader()
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        if (!res.write(value)) {
+          await new Promise((resolve) => res.once('drain', resolve))
+        }
+      }
+      res.end()
+    } catch (error) {
+      try {
+        await reader.cancel()
+      } catch {
+        // Ignore cancel errors
+      }
+      if (!res.destroyed) {
+        res.destroy()
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Handles proxy errors and sends appropriate response to client
+   */
+  private handleProxyError(error: unknown, res: ServerResponse): void {
+    if (this.options.onError) {
+      this.options.onError({
+        from: this.options.sourceBaseUrl,
+        to: this.options.targetBaseUrl,
+        error,
+      })
+    }
+
+    if (!res.headersSent) {
+      res.writeHead(502, { 'Content-Type': 'text/plain' })
+      res.end('Bad Gateway')
+    } else if (!res.destroyed) {
+      res.destroy()
+    }
+  }
+
+  /**
+   * Main handler for proxying HTTP requests
+   */
+  public async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    try {
+      // Build target URL
+      const targetUrl = this.pathProcessor.processUrl(
+        req.url as string,
+        this.options.sourceBaseUrl,
+        this.options.targetBaseUrl,
+        this.options.pathRewrite,
+      )
+
+      const parsedTargetUrl = new URL(targetUrl)
+
+      // Process headers
+      const { proxyHeaders } = this.headerProcessor.processRequestHeaders(req, parsedTargetUrl.host, {
+        headers: this.options.headers,
+        cookies: this.options.cookies,
+      })
+
+      // Set up timeout and abort handling
+      const timeoutMs = this.options.timeout ?? 30000
+      const { abortController, timeoutId } = this.setupAbortHandling(req, res, timeoutMs)
+
+      try {
+        // Make the proxy request
+        const proxyResponse = await fetch(targetUrl, {
+          method: req.method,
+          headers: proxyHeaders,
+          body:
+            req.method !== 'GET' && req.method !== 'HEAD'
+              ? (Readable.toWeb(req) as ReadableStream<Uint8Array>)
+              : undefined,
+          // @ts-expect-error - duplex is not in the types yet, but required for streaming bodies
+          duplex: 'half',
+          signal: abortController.signal,
+        })
+        clearTimeout(timeoutId)
+
+        // Extract and handle Set-Cookie headers
+        const setCookieHeaders = this.extractSetCookieHeaders(proxyResponse)
+
+        // Copy other response headers
+        this.copyResponseHeaders(proxyResponse, res)
+
+        // Handle Set-Cookie headers with transformation
+        this.handleSetCookieHeaders(setCookieHeaders, res)
+
+        // Set status code
+        res.writeHead(proxyResponse.status, res.getHeaders())
+
+        // Stream the response body
+        await this.streamResponseBody(proxyResponse, res)
+      } catch (error) {
+        clearTimeout(timeoutId)
+        throw error
+      }
+    } catch (error) {
+      this.handleProxyError(error, res)
+    }
+  }
+}

package/src/http-user-context.ts

@@ -1,11 +1,11 @@
-import type { IncomingMessage } from 'http'
 import type { User } from '@furystack/core'
 import { StoreManager } from '@furystack/core'
 import { Injectable, Injected } from '@furystack/inject'
-import { HttpAuthenticationSettings } from './http-authentication-settings.js'
-import type { DefaultSession } from './models/default-session.js'
 import { PasswordAuthenticator, UnauthenticatedError } from '@furystack/security'
 import { randomBytes } from 'crypto'
+import type { IncomingMessage } from 'http'
+import { HttpAuthenticationSettings } from './http-authentication-settings.js'
+import type { DefaultSession } from './models/default-session.js'
 
 /**
  * Injectable UserContext for FuryStack HTTP Api
@@ -38,7 +38,7 @@ export class HttpUserContext {
 
   /**
    * @param request The request to be authenticated
-   * @returns if the current user is authenticated
+   * @returns whether the current user is authenticated
    */
   public async isAuthenticated(request: IncomingMessage) {
     try {
@@ -50,10 +50,10 @@ export class HttpUserContext {
   }
 
   /**
-   * Returns if the current user can be authorized with ALL of the specified roles
+   * Returns whether the current user can be authorized with ALL of the specified roles
    * @param request The request to be authenticated
    * @param roles The list of roles to authorize
-   * @returns a boolean value that indicates if the user is authenticated
+   * @returns a boolean value that indicates whether the user is authorized
    */
   public async isAuthorized(request: IncomingMessage, ...roles: string[]): Promise<boolean> {
     const currentUser = await this.getCurrentUser(request)

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './http-authentication-settings.js'
 export * from './http-user-context.js'
 export * from './mime-types.js'
 export * from './models/index.js'
+export * from './proxy-manager.js'
 export * from './read-post-body.js'
 export * from './request-action-implementation.js'
 export * from './schema-validator/index.js'

package/src/path-processor.spec.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from 'vitest'
+import { PathProcessor } from './path-processor.js'
+
+describe('PathProcessor', () => {
+  const processor = new PathProcessor()
+
+  describe('validateUrl', () => {
+    it('should validate and return a valid URL', () => {
+      const url = processor.validateUrl('http://example.com/path')
+      expect(url).toBeInstanceOf(URL)
+      expect(url.href).toBe('http://example.com/path')
+    })
+
+    it('should throw error for invalid URL', () => {
+      expect(() => processor.validateUrl('not-a-valid-url')).toThrow('Invalid URL')
+    })
+
+    it('should include context in error message', () => {
+      expect(() => processor.validateUrl('invalid', 'targetBaseUrl')).toThrow('Invalid targetBaseUrl')
+    })
+
+    it('should validate HTTPS URLs', () => {
+      const url = processor.validateUrl('https://secure.example.com')
+      expect(url.protocol).toBe('https:')
+    })
+
+    it('should validate URLs with query strings', () => {
+      const url = processor.validateUrl('http://example.com/path?foo=bar')
+      expect(url.search).toBe('?foo=bar')
+    })
+  })
+
+  describe('validateHttpProtocol', () => {
+    it('should accept HTTP protocol', () => {
+      const url = new URL('http://example.com')
+      expect(() => processor.validateHttpProtocol(url)).not.toThrow()
+    })
+
+    it('should accept HTTPS protocol', () => {
+      const url = new URL('https://example.com')
+      expect(() => processor.validateHttpProtocol(url)).not.toThrow()
+    })
+
+    it('should reject FTP protocol', () => {
+      const url = new URL('ftp://example.com')
+      expect(() => processor.validateHttpProtocol(url)).toThrow('Invalid targetBaseUrl protocol: ftp:')
+    })
+
+    it('should reject WS protocol', () => {
+      const url = new URL('ws://example.com')
+      expect(() => processor.validateHttpProtocol(url)).toThrow('Invalid targetBaseUrl protocol: ws:')
+    })
+
+    it('should reject file protocol', () => {
+      const url = new URL('file:///path/to/file')
+      expect(() => processor.validateHttpProtocol(url)).toThrow('Invalid targetBaseUrl protocol: file:')
+    })
+  })
+
+  describe('extractSourcePath', () => {
+    it('should extract path after source base URL', () => {
+      const path = processor.extractSourcePath('/api/users/123', '/api')
+      expect(path).toBe('/users/123')
+    })
+
+    it('should extract empty path when URL matches exactly', () => {
+      const path = processor.extractSourcePath('/api', '/api')
+      expect(path).toBe('')
+    })
+
+    it('should preserve query strings', () => {
+      const path = processor.extractSourcePath('/api/users?page=1&limit=10', '/api')
+      expect(path).toBe('/users?page=1&limit=10')
+    })
+
+    it('should handle source base URL with trailing slash', () => {
+      const path = processor.extractSourcePath('/api/users/123', '/api/')
+      // PathHelper.extractPath now consistently returns paths with leading slashes
+      expect(path).toBe('/users/123')
+    })
+  })
+
+  describe('applyPathRewrite', () => {
+    it('should return path as-is when no rewrite function provided', () => {
+      const path = processor.applyPathRewrite('/users/123')
+      expect(path).toBe('/users/123')
+    })
+
+    it('should apply rewrite function when provided', () => {
+      const rewrite = (path: string) => path.replace('/old', '/new')
+      const path = processor.applyPathRewrite('/old/path', rewrite)
+      expect(path).toBe('/new/path')
+    })
+
+    it('should handle complex rewrite logic', () => {
+      const rewrite = (path: string) => {
+        // Remove version prefix
+        return path.replace(/^\/v\d+/, '')
+      }
+      const path = processor.applyPathRewrite('/v1/users/123', rewrite)
+      expect(path).toBe('/users/123')
+    })
+
+    it('should allow complete path transformation', () => {
+      const rewrite = () => '/completely/different/path'
+      const path = processor.applyPathRewrite('/original', rewrite)
+      expect(path).toBe('/completely/different/path')
+    })
+  })
+
+  describe('buildTargetUrl', () => {
+    it('should combine base URL and path', () => {
+      const url = processor.buildTargetUrl('http://example.com', '/api/users')
+      expect(url).toBe('http://example.com/api/users')
+    })
+
+    it('should handle base URL with trailing slash', () => {
+      const url = processor.buildTargetUrl('http://example.com/', '/api/users')
+      // PathHelper.joinUrl now correctly handles trailing slashes, avoiding double slashes
+      expect(url).toBe('http://example.com/api/users')
+    })
+
+    it('should preserve query strings in path', () => {
+      const url = processor.buildTargetUrl('http://example.com', '/api/users?page=1')
+      expect(url).toBe('http://example.com/api/users?page=1')
+    })
+
+    it('should handle empty path', () => {
+      const url = processor.buildTargetUrl('http://example.com', '')
+      expect(url).toBe('http://example.com')
+    })
+  })
+
+  describe('processUrl', () => {
+    it('should process complete URL transformation', () => {
+      const url = processor.processUrl('/api/users/123', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/users/123')
+    })
+
+    it('should apply path rewrite during processing', () => {
+      const rewrite = (path: string) => path.replace('/old', '/new')
+      const url = processor.processUrl('/api/old/path', '/api', 'http://target.com', rewrite)
+      expect(url).toBe('http://target.com/new/path')
+    })
+
+    it('should preserve query strings', () => {
+      const url = processor.processUrl('/api/users?page=1&limit=10', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/users?page=1&limit=10')
+    })
+
+    it('should throw error for invalid resulting URL', () => {
+      // Use a base URL that when combined with the rewritten path will be invalid
+      const rewrite = () => '://invalid-path'
+      expect(() => processor.processUrl('/api/test', '/api', 'http:', rewrite)).toThrow('Invalid')
+    })
+
+    it('should handle complex source URLs', () => {
+      const url = processor.processUrl(
+        '/proxy/v1/api/users/123?sort=name&order=asc',
+        '/proxy',
+        'http://backend.example.com:8080',
+      )
+      expect(url).toBe('http://backend.example.com:8080/v1/api/users/123?sort=name&order=asc')
+    })
+
+    it('should work with HTTPS target URLs', () => {
+      const url = processor.processUrl('/api/secure', '/api', 'https://secure.example.com')
+      expect(url).toBe('https://secure.example.com/secure')
+    })
+
+    it('should handle exact URL matches', () => {
+      const url = processor.processUrl('/api', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com')
+    })
+
+    it('should validate the resulting target URL', () => {
+      // This should not throw because the result is valid
+      expect(() => processor.processUrl('/api/test', '/api', 'http://target.com')).not.toThrow()
+    })
+  })
+
+  describe('Edge cases and complex scenarios', () => {
+    it('should handle very long URLs', () => {
+      const longPath = `/api${'/segment'.repeat(100)}`
+      const url = processor.processUrl(longPath, '/api', 'http://target.com')
+      expect(url).toContain('target.com')
+      expect(url).toContain('/segment')
+    })
+
+    it('should handle URLs with special characters in path', () => {
+      const url = processor.processUrl('/api/path%20with%20spaces', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/path%20with%20spaces')
+    })
+
+    it('should handle URLs with encoded special characters', () => {
+      const url = processor.processUrl('/api/user%2Fname', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/user%2Fname')
+    })
+
+    it('should handle URLs with hash fragments', () => {
+      const url = processor.processUrl('/api/resource#section', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/resource#section')
+    })
+
+    it('should handle multiple query parameters', () => {
+      const url = processor.processUrl('/api/search?q=test&sort=date&order=desc&page=1', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/search?q=test&sort=date&order=desc&page=1')
+    })
+
+    it('should handle empty query parameter values', () => {
+      const url = processor.processUrl('/api/test?empty=&another=value', '/api', 'http://target.com')
+      expect(url).toBe('http://target.com/test?empty=&another=value')
+    })
+
+    it('should handle source base URL ending with slash and path starting with slash', () => {
+      const path = processor.extractSourcePath('/api//users', '/api/')
+      // PathHelper.extractPath preserves the double slash from the input URL
+      // If normalization is needed, it should be done on the input URL first
+      expect(path).toBe('//users')
+    })
+
+    it('should handle double slashes in paths', () => {
+      const url = processor.buildTargetUrl('http://target.com', '//path//to//resource')
+      // PathHelper.joinUrl preserves the double slash at the start since it's already there
+      expect(url).toBe('http://target.com//path//to//resource')
+    })
+
+    it('should handle target URLs with ports', () => {
+      const url = processor.processUrl('/api/test', '/api', 'http://target.com:8080')
+      expect(url).toBe('http://target.com:8080/test')
+    })
+
+    it('should handle target URLs with paths', () => {
+      const url = processor.processUrl('/api/test', '/api', 'http://target.com/base')
+      expect(url).toBe('http://target.com/base/test')
+    })
+
+    it('should validate URL with only protocol', () => {
+      expect(() => processor.validateUrl('http://')).toThrow('Invalid URL')
+    })
+
+    it('should handle path rewrite that adds query parameters', () => {
+      const rewrite = (path: string) => `${path}?added=param`
+      const url = processor.processUrl('/api/test?existing=value', '/api', 'http://target.com', rewrite)
+      expect(url).toBe('http://target.com/test?existing=value?added=param')
+    })
+
+    it('should handle path rewrite that removes path completely', () => {
+      const rewrite = () => ''
+      const url = processor.processUrl('/api/test', '/api', 'http://target.com', rewrite)
+      expect(url).toBe('http://target.com')
+    })
+
+    it('should handle path rewrite that adds leading slash', () => {
+      const rewrite = (path: string) => `/${path}`
+      const url = processor.processUrl('/api/test', '/api', 'http://target.com', rewrite)
+      expect(url).toBe('http://target.com//test')
+    })
+
+    it('should validate HTTPS URLs with authentication', () => {
+      const url = processor.validateUrl('https://user:pass@example.com/path')
+      expect(url.protocol).toBe('https:')
+      expect(url.username).toBe('user')
+      expect(url.password).toBe('pass')
+    })
+
+    it('should handle URLs with international domain names', () => {
+      const url = processor.validateUrl('http://例え.jp/path')
+      expect(url.hostname).toBeTruthy()
+    })
+
+    it('should handle target URLs with trailing slash and path without leading slash', () => {
+      const url = processor.buildTargetUrl('http://target.com/', 'path')
+      expect(url).toBe('http://target.com/path')
+    })
+
+    it('should extract path with multiple slashes in source base URL', () => {
+      const path = processor.extractSourcePath('/api//users', '/api')
+      expect(path).toBe('//users')
+    })
+
+    it('should handle complex path rewrite with regex', () => {
+      const rewrite = (path: string) => path.replace(/\/v\d+\//, '/')
+      const url = processor.processUrl('/api/v2/users', '/api', 'http://target.com', rewrite)
+      expect(url).toBe('http://target.com/users')
+    })
+
+    it('should validate data URLs are rejected', () => {
+      expect(() => processor.validateHttpProtocol(new URL('data:text/plain,hello'))).toThrow(
+        'Invalid targetBaseUrl protocol',
+      )
+    })
+
+    it('should validate mailto URLs are rejected', () => {
+      expect(() => processor.validateHttpProtocol(new URL('mailto:test@example.com'))).toThrow(
+        'Invalid targetBaseUrl protocol',
+      )
+    })
+
+    it('should handle IPv4 addresses in URLs', () => {
+      const url = processor.validateUrl('http://192.168.1.1:8080/path')
+      expect(url.hostname).toBe('192.168.1.1')
+      expect(url.port).toBe('8080')
+    })
+
+    it('should handle IPv6 addresses in URLs', () => {
+      const url = processor.validateUrl('http://[::1]:8080/path')
+      expect(url.hostname).toBe('[::1]')
+      expect(url.port).toBe('8080')
+    })
+
+    it('should handle localhost in URLs', () => {
+      const url = processor.validateUrl('http://localhost:3000/api')
+      expect(url.hostname).toBe('localhost')
+      expect(url.port).toBe('3000')
+    })
+  })
+})