@api-client/core 0.18.12 → 0.18.13

package/src/runtime/http-engine/connections/TunnelConnection.ts

@@ -0,0 +1,192 @@
+import net from 'net'
+import tls from 'tls'
+import https from 'https'
+import http from 'http'
+import { URL } from 'url'
+import { TunnelConnectionOptions } from './ConnectionManager.js'
+import { Headers } from '../../../lib/headers/Headers.js'
+import { ProxyAuthHandler } from './ProxyAuthHandler.js'
+import { HttpEngineErrorFactory } from '../errors/index.js'
+
+/**
+ * Handles HTTPS tunneling through an HTTP proxy
+ */
+export class TunnelConnection {
+  private options: TunnelConnectionOptions
+  private authHandler: ProxyAuthHandler
+
+  constructor(options: TunnelConnectionOptions) {
+    this.options = options
+    this.authHandler = new ProxyAuthHandler({
+      proxyUsername: options.proxyUsername,
+      proxyPassword: options.proxyPassword,
+      logger: options.logger,
+    })
+  }
+
+  async connect(): Promise<net.Socket> {
+    const { proxy, proxyIsSsl, targetHost, targetPort, logger, stats } = this.options
+
+    logger.debug('Creating a tunnel through the proxy...')
+
+    if (!proxy) {
+      throw HttpEngineErrorFactory.proxyConfigError('No proxy configuration found.')
+    }
+
+    let proxyUrl = proxy
+    if (proxyIsSsl && !proxyUrl.startsWith('https:')) {
+      proxyUrl = `https://${proxyUrl}`
+    } else if (!proxyIsSsl && !proxyUrl.startsWith('http:')) {
+      proxyUrl = `http://${proxyUrl}`
+    }
+
+    const proxyUri = new URL(proxyUrl)
+    const proxyPort = proxyUri.port || (proxyIsSsl ? 443 : 80)
+    const authority = `${targetHost}:${targetPort}`
+
+    const connectOptions: https.RequestOptions = {
+      host: proxyUri.hostname,
+      port: proxyPort,
+      method: 'CONNECT',
+      path: authority,
+      headers: {
+        host: authority,
+      },
+    }
+
+    if (proxyIsSsl) {
+      connectOptions.rejectUnauthorized = false
+      // @ts-expect-error This is correct!
+      connectOptions.requestOCSP = false
+    }
+
+    const lib = proxyIsSsl ? https : http
+
+    return new Promise((resolve, reject) => {
+      stats.connectionTime = Date.now()
+      try {
+        // Add proxy authorization if available
+        const auth = this.authHandler.generateAuthHeader()
+        if (auth) {
+          logger.debug('Adding proxy authorization.')
+          ;(connectOptions.headers as http.OutgoingHttpHeaders)['proxy-authorization'] = auth
+        }
+        logger.debug('Creating proxy tunnel...')
+        const connectRequest = lib.request(connectOptions)
+        logger.silly('Proxy tunnel created.')
+        connectRequest.once('socket', (socket: net.Socket) => {
+          logger.debug('Proxy tunnel socket created.')
+          socket.on('lookup', () => {
+            logger.debug('Proxy tunnel lookup.')
+            stats.lookupTime = Date.now()
+          })
+        })
+
+        connectRequest.on('error', (err) => {
+          logger.error('Error establishing proxy tunnel:', err)
+          reject(
+            HttpEngineErrorFactory.proxyError(
+              `Failed to establish proxy tunnel: ${err.message}`,
+              (err as Error & { code: string }).code ? Number((err as Error & { code: string }).code) : 111
+            )
+          )
+        })
+
+        connectRequest.on('connect', async (res: http.IncomingMessage, socket: net.Socket, head: Buffer) => {
+          const time = Date.now()
+          logger.debug('Proxy tunnel connected.')
+          stats.connectedTime = time
+          stats.secureStartTime = time
+          if (typeof stats.lookupTime === 'undefined') {
+            stats.lookupTime = time
+          }
+
+          if (res.statusCode === 401) {
+            // Handle proxy authentication required
+            logger.debug('Proxy tunnel not authorized. Closing.')
+            connectRequest.destroy()
+            reject(HttpEngineErrorFactory.proxyAuthRequired(res, head))
+            return
+          } else if (res.statusCode === 407) {
+            // Handle proxy authentication
+            logger.debug('Proxy tunnel authentication required. Trying to authenticate...')
+            try {
+              const retryResult = await this.handleProxyAuthentication(res)
+              if (retryResult) {
+                // Authentication succeeded and we should retry
+                connectRequest.destroy()
+                socket.destroy()
+
+                // Retry the connection with new authentication
+                try {
+                  const retrySocket = await this.connect()
+                  resolve(retrySocket)
+                } catch (retryError) {
+                  reject(retryError)
+                }
+                return
+              } else {
+                // Authentication failed
+                logger.warn('Proxy authentication failed. Closing connection.')
+                connectRequest.destroy()
+                reject(HttpEngineErrorFactory.proxyAuthFailed())
+                return
+              }
+            } catch (error) {
+              logger.warn('Error handling proxy authentication:', error)
+              connectRequest.destroy()
+              reject(error)
+            }
+            return
+          } else if (res.statusCode !== 200) {
+            logger.debug(`The proxy tunnel ended with ${res.statusCode} status code. Erroring request.`)
+            connectRequest.destroy()
+            const errorMessage =
+              res.statusMessage || `Proxy tunnel establishment failed with status code ${res.statusCode}`
+            const e = HttpEngineErrorFactory.proxyError(errorMessage, res.statusCode)
+            reject(e)
+            return
+          }
+
+          logger.debug('Established a proxy tunnel.')
+          logger.debug('Upgrading connection to SSL...')
+          const tlsSocket = tls.connect({ socket, rejectUnauthorized: false }, () => {
+            logger.debug('Connection upgraded to SSL.')
+            resolve(tlsSocket)
+          })
+          tlsSocket.once('secureConnect', () => {
+            stats.secureConnectedTime = Date.now()
+          })
+        })
+
+        connectRequest.end()
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  private async handleProxyAuthentication(res: http.IncomingMessage): Promise<boolean> {
+    if (res.statusCode === 407) {
+      const headers = new Headers(res.headers)
+      const authHeader = headers.get('proxy-authenticate')
+
+      if (authHeader) {
+        try {
+          const authResponse = this.authHandler.handleChallenge(authHeader)
+          if (authResponse) {
+            this.options.logger.debug('Generated proxy authentication response')
+            this.authHandler.markAuthenticated()
+            return true // Indicate successful authentication
+          }
+        } catch (error) {
+          this.options.logger.error('Failed to handle proxy authentication:', error)
+          throw error
+        }
+      } else {
+        throw HttpEngineErrorFactory.proxyError('Proxy authentication required but no challenge provided', 407)
+      }
+    }
+    return false // Indicate failed authentication
+  }
+}

package/src/runtime/http-engine/constants.ts

@@ -0,0 +1,103 @@
+/**
+ * HTTP constants used throughout the HTTP engine
+ */
+
+// HTTP Status Code Ranges
+export const REDIRECT_START = 300
+export const REDIRECT_END = 399
+export const CLIENT_ERROR_START = 400
+export const CLIENT_ERROR_END = 499
+export const SERVER_ERROR_START = 500
+export const SERVER_ERROR_END = 599
+
+// Specific Status Codes
+export const STATUS_OK = 200
+export const STATUS_MOVED_PERMANENTLY = 301
+export const STATUS_FOUND = 302
+export const STATUS_SEE_OTHER = 303
+export const STATUS_NOT_MODIFIED = 304
+export const STATUS_USE_PROXY = 305
+export const STATUS_TEMPORARY_REDIRECT = 307
+export const STATUS_PERMANENT_REDIRECT = 308
+export const STATUS_UNAUTHORIZED = 401
+export const STATUS_PROXY_AUTHENTICATION_REQUIRED = 407
+
+// HTTP Methods
+export const METHOD_GET = 'GET'
+export const METHOD_HEAD = 'HEAD'
+export const METHOD_POST = 'POST'
+export const METHOD_PUT = 'PUT'
+export const METHOD_DELETE = 'DELETE'
+export const METHOD_PATCH = 'PATCH'
+export const METHOD_OPTIONS = 'OPTIONS'
+export const METHOD_TRACE = 'TRACE'
+export const METHOD_CONNECT = 'CONNECT'
+
+// HTTP Headers
+export const HEADER_HOST = 'host'
+export const HEADER_AUTHORIZATION = 'authorization'
+export const HEADER_PROXY_AUTHORIZATION = 'proxy-authorization'
+export const HEADER_CONNECTION = 'connection'
+export const HEADER_CONTENT_LENGTH = 'content-length'
+export const HEADER_TRANSFER_ENCODING = 'transfer-encoding'
+export const HEADER_WWW_AUTHENTICATE = 'www-authenticate'
+export const HEADER_PROXY_AUTHENTICATE = 'proxy-authenticate'
+
+// HTTP Values
+export const KEEP_ALIVE = 'keep-alive'
+export const CHUNKED = 'chunked'
+export const HTTP_VERSION = 'HTTP/1.1'
+
+// Buffer Constants
+export const CRLF = '\r\n'
+export const CRLF_BUFFER = Buffer.from([13, 10, 13, 10]) // \r\n\r\n
+
+// Timeout Constants
+export const DEFAULT_TIMEOUT = 30000 // 30 seconds
+export const DEFAULT_CONNECT_TIMEOUT = 10000 // 10 seconds
+
+// Chunked Transfer Constants
+export const CHUNK_SIZE_HEX_BASE = 16
+export const MAX_CHUNK_SIZE = 0x1000000 // 16MB
+
+// Authentication Constants
+export const NTLM_PREFIX = 'NTLM '
+export const BASIC_PREFIX = 'Basic '
+export const DIGEST_PREFIX = 'Digest '
+
+/**
+ * Check if a status code indicates a redirect
+ */
+export function isRedirect(status: number): boolean {
+  return status >= REDIRECT_START && status <= REDIRECT_END
+}
+
+/**
+ * Check if a status code indicates a client error
+ */
+export function isClientError(status: number): boolean {
+  return status >= CLIENT_ERROR_START && status <= CLIENT_ERROR_END
+}
+
+/**
+ * Check if a status code indicates a server error
+ */
+export function isServerError(status: number): boolean {
+  return status >= SERVER_ERROR_START && status <= SERVER_ERROR_END
+}
+
+/**
+ * Check if a method should not have a body
+ */
+export function isMethodWithoutBody(method: string): boolean {
+  const upperMethod = method.toUpperCase()
+  return upperMethod === METHOD_GET || upperMethod === METHOD_HEAD
+}
+
+/**
+ * Check if a method is safe (should not have side effects)
+ */
+export function isSafeMethod(method: string): boolean {
+  const upperMethod = method.toUpperCase()
+  return upperMethod === METHOD_GET || upperMethod === METHOD_HEAD || upperMethod === METHOD_OPTIONS
+}

package/src/runtime/http-engine/cookies/CookieProcessor.ts

@@ -0,0 +1,25 @@
+import { Headers } from '../../../lib/headers/Headers.js'
+import { CookieParser } from '../../../cookies/CookieParser.js'
+
+/**
+ * Handles cookie exchange when redirecting the request.
+ */
+export function processRedirectCookies(
+  responseCookies: string,
+  location: string,
+  requestUrl: string,
+  requestHeaders: string
+): string {
+  const received = CookieParser.parse(requestUrl, responseCookies)
+  const forwardCookies = CookieParser.filterCookies(received, location)
+  const headers = new Headers(requestHeaders)
+  headers.delete('cookie')
+  if (forwardCookies.length) {
+    const parts: string[] = []
+    forwardCookies.forEach((cookie) => {
+      parts.push(cookie.toString())
+    })
+    headers.set('cookie', parts.join('; '))
+  }
+  return headers.toString()
+}

package/src/runtime/http-engine/errors/HttpEngineErrors.ts

@@ -0,0 +1,319 @@
+import type { IncomingMessage } from 'http'
+import { SerializableError } from '../../../models/SerializableError.js'
+
+/**
+ * Base class for all HTTP engine errors
+ */
+export class HttpEngineError extends SerializableError {
+  readonly category: string
+
+  constructor(message: string, code?: number | string, category = 'general') {
+    super(message, code)
+    this.category = category
+  }
+}
+
+/**
+ * Connection-related errors
+ */
+export class ConnectionError extends HttpEngineError {
+  readonly connectionType: 'direct' | 'proxy' | 'tunnel'
+
+  constructor(message: string, code?: number | string, connectionType: 'direct' | 'proxy' | 'tunnel' = 'direct') {
+    super(message, code, 'connection')
+    this.connectionType = connectionType
+  }
+}
+
+/**
+ * Authentication-related errors
+ */
+export class AuthenticationError extends HttpEngineError {
+  readonly authType: 'request' | 'proxy' | 'digest' | 'basic' | 'ntlm'
+
+  constructor(
+    message: string,
+    code?: number | string,
+    authType: 'request' | 'proxy' | 'digest' | 'basic' | 'ntlm' = 'request'
+  ) {
+    super(message, code, 'authentication')
+    this.authType = authType
+  }
+}
+
+/**
+ * Message building errors
+ */
+export class MessageBuilderError extends HttpEngineError {
+  readonly component: 'status' | 'headers' | 'body' | 'host'
+
+  constructor(message: string, code?: number | string, component: 'status' | 'headers' | 'body' | 'host' = 'headers') {
+    super(message, code, 'message')
+    this.component = component
+  }
+}
+
+/**
+ * Response parsing errors
+ */
+export class ResponseParsingError extends HttpEngineError {
+  readonly parsingStage: 'status' | 'headers' | 'body' | 'chunked'
+
+  constructor(
+    message: string,
+    code?: number | string,
+    parsingStage: 'status' | 'headers' | 'body' | 'chunked' = 'headers'
+  ) {
+    super(message, code, 'parsing')
+    this.parsingStage = parsingStage
+  }
+}
+
+/**
+ * Timeout errors
+ */
+export class TimeoutError extends HttpEngineError {
+  readonly timeoutType: 'connection' | 'request' | 'response'
+
+  constructor(message: string, code?: number | string, timeoutType: 'connection' | 'request' | 'response' = 'request') {
+    super(message, code, 'timeout')
+    this.timeoutType = timeoutType
+  }
+}
+
+/**
+ * Proxy-related errors
+ */
+export class ProxyError extends HttpEngineError {
+  readonly proxyStage: 'connection' | 'authentication' | 'tunneling' | 'configuration'
+  override name = 'ProxyError'
+
+  constructor(
+    message: string,
+    code?: number | string,
+    proxyStage: 'connection' | 'authentication' | 'tunneling' | 'configuration' = 'connection'
+  ) {
+    super(message, code, 'proxy')
+    this.proxyStage = proxyStage
+  }
+}
+
+/**
+ * Proxy authentication error
+ */
+export class ProxyAuthenticationError extends HttpEngineError {
+  override name = 'ProxyAuthenticationError'
+
+  constructor(
+    message: string,
+    code: number | string,
+    readonly response: IncomingMessage,
+    readonly head: Buffer
+  ) {
+    super(message, code, 'proxy')
+  }
+}
+
+/**
+ * Payload-related errors
+ */
+export class PayloadError extends HttpEngineError {
+  readonly payloadType: 'serialization' | 'validation' | 'unsupported'
+
+  constructor(
+    message: string,
+    code?: number | string,
+    payloadType: 'serialization' | 'validation' | 'unsupported' = 'validation'
+  ) {
+    super(message, code, 'payload')
+    this.payloadType = payloadType
+  }
+}
+
+/**
+ * URL parsing errors
+ */
+export class UrlParsingError extends HttpEngineError {
+  readonly url: string
+
+  constructor(message: string, url: string, code?: number | string) {
+    super(message, code, 'url')
+    this.url = url
+  }
+}
+
+/**
+ * Configuration errors
+ */
+export class ConfigurationError extends HttpEngineError {
+  readonly configType: 'request' | 'proxy' | 'auth' | 'timeout'
+
+  constructor(
+    message: string,
+    code?: number | string,
+    configType: 'request' | 'proxy' | 'auth' | 'timeout' = 'request'
+  ) {
+    super(message, code, 'configuration')
+    this.configType = configType
+  }
+}
+
+/**
+ * Error factory for creating specific error types
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class HttpEngineErrorFactory {
+  /**
+   * Create a connection error
+   */
+  static connectionError(
+    message: string,
+    code?: number | string,
+    connectionType?: 'direct' | 'proxy' | 'tunnel'
+  ): ConnectionError {
+    return new ConnectionError(message, code, connectionType)
+  }
+
+  /**
+   * Create an authentication error
+   */
+  static authenticationError(
+    message: string,
+    code?: number | string,
+    authType?: 'request' | 'proxy' | 'digest' | 'basic' | 'ntlm'
+  ): AuthenticationError {
+    return new AuthenticationError(message, code, authType)
+  }
+
+  /**
+   * Create a message builder error
+   */
+  static messageBuilderError(
+    message: string,
+    code?: number | string,
+    component?: 'status' | 'headers' | 'body' | 'host'
+  ): MessageBuilderError {
+    return new MessageBuilderError(message, code, component)
+  }
+
+  /**
+   * Create a response parsing error
+   */
+  static responseParsingError(
+    message: string,
+    code?: number | string,
+    parsingStage?: 'status' | 'headers' | 'body' | 'chunked'
+  ): ResponseParsingError {
+    return new ResponseParsingError(message, code, parsingStage)
+  }
+
+  /**
+   * Create a timeout error
+   */
+  static timeoutError(
+    message: string,
+    code?: number | string,
+    timeoutType?: 'connection' | 'request' | 'response'
+  ): TimeoutError {
+    return new TimeoutError(message, code, timeoutType)
+  }
+
+  /**
+   * Create a proxy error
+   */
+  static proxyError(
+    message: string,
+    code?: number | string,
+    proxyStage?: 'connection' | 'authentication' | 'tunneling' | 'configuration'
+  ): ProxyError {
+    return new ProxyError(message, code, proxyStage)
+  }
+
+  /**
+   * Create a payload error
+   */
+  static payloadError(
+    message: string,
+    code?: number | string,
+    payloadType?: 'serialization' | 'validation' | 'unsupported'
+  ): PayloadError {
+    return new PayloadError(message, code, payloadType)
+  }
+
+  /**
+   * Create a URL parsing error
+   */
+  static urlParsingError(message: string, url: string, code?: number | string): UrlParsingError {
+    return new UrlParsingError(message, url, code)
+  }
+
+  /**
+   * Create a configuration error
+   */
+  static configurationError(
+    message: string,
+    code?: number | string,
+    configType?: 'request' | 'proxy' | 'auth' | 'timeout'
+  ): ConfigurationError {
+    return new ConfigurationError(message, code, configType)
+  }
+
+  /**
+   * Convert a generic error to an HTTP engine error
+   */
+  static fromError(error: Error, category = 'general'): HttpEngineError {
+    if (error instanceof HttpEngineError) {
+      return error
+    }
+    return new HttpEngineError(error.message, undefined, category)
+  }
+
+  /**
+   * Create a connection timeout error
+   */
+  static connectionTimeout(timeoutMs: number): TimeoutError {
+    return new TimeoutError(`Connection timeout after ${timeoutMs}ms`, 408, 'connection')
+  }
+
+  /**
+   * Create a request timeout error
+   */
+  static requestTimeout(timeoutMs: number): TimeoutError {
+    return new TimeoutError(`Request timeout after ${timeoutMs}ms`, 408, 'request')
+  }
+
+  /**
+   * Create a proxy authentication error
+   */
+  static proxyAuthRequired(res: IncomingMessage, head: Buffer): ProxyAuthenticationError {
+    return new ProxyAuthenticationError('Proxy authentication required', 407, res, head)
+  }
+
+  /**
+   * Create a proxy authentication failed error
+   */
+  static proxyAuthFailed(): AuthenticationError {
+    return new AuthenticationError('Proxy authentication failed', 407, 'proxy')
+  }
+
+  /**
+   * Create a proxy configuration error
+   */
+  static proxyConfigError(message: string): ProxyError {
+    return new ProxyError(message, 400, 'configuration')
+  }
+
+  /**
+   * Create a payload serialization error
+   */
+  static payloadSerializationError(message: string): PayloadError {
+    return new PayloadError(message, 400, 'serialization')
+  }
+
+  /**
+   * Create an unsupported payload error
+   */
+  static unsupportedPayload(payloadType: string): PayloadError {
+    return new PayloadError(`Unsupported payload type: ${payloadType}`, 400, 'unsupported')
+  }
+}