@apiquest/plugin-http 1.0.2

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+import type { IProtocolPlugin } from '@apiquest/types';
+export declare const httpPlugin: IProtocolPlugin;
+export default httpPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAA2G,MAAM,iBAAiB,CAAC;AAmBhK,eAAO,MAAM,UAAU,EAAE,eAmRxB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/esbuild.config.js

@@ -0,0 +1,34 @@
+import esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  outfile: 'dist/index.js',
+  format: 'esm',
+  platform: 'node',
+  target: 'node18',
+  // Externalize peerDependencies and Node.js built-ins
+  external: [
+    '@apiquest/fracture',
+    // Node.js built-in modules (got depends on these)
+    'http',
+    'https',
+    'http2',
+    'net',
+    'tls',
+    'stream',
+    'util',
+    'url',
+    'zlib',
+    'events',
+    'buffer',
+    'querystring',
+    'dns',
+    'fs',
+    'path',
+  ],
+  minify: false,
+  sourcemap: true,
+});
+
+console.log('✓ Built plugin-http');

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@apiquest/plugin-http",
+  "version": "1.0.2",
+  "description": "HTTP protocol plugin for Quest",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly",
+    "dev": "rollup -c --watch",
+    "test": "vitest"
+  },
+  "keywords": [
+    "api",
+    "http",
+    "quest",
+    "plugin"
+  ],
+  "author": "ApiQuest",
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "got": "^14.6.6",
+    "hpagent": "^1.2.0"
+  },
+  "devDependencies": {
+    "@apiquest/types": "workspace:*",
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@types/node": "^20.10.6",
+    "rollup": "^4.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@apiquest/types": "^1.0.0"
+  },
+  "apiquest": {
+    "type": "protocol",
+    "runtime": [
+      "fracture"
+    ],
+    "capabilities": {
+      "provides": {
+        "protocols": [
+          "http"
+        ]
+      },
+      "supports": {
+        "authTypes": [
+          "bearer",
+          "basic",
+          "oauth2",
+          "apikey",
+          "digest",
+          "ntlm"
+        ],
+        "strictAuthList": false
+      }
+    }
+  }
+}

package/rollup.config.js

@@ -0,0 +1,31 @@
+import typescript from '@rollup/plugin-typescript';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+
+export default {
+  input: 'src/index.ts',
+  output: {
+    file: 'dist/index.js',
+    format: 'esm',
+    sourcemap: true,
+  },
+  external: [
+    // Externalize peer dependencies
+    '@apiquest/fracture',
+  ],
+  plugins: [
+    // Resolve node modules
+    resolve({
+      preferBuiltins: true,  // Prefer Node.js built-in modules
+      exportConditions: ['node', 'import', 'default'],
+    }),
+    // Convert CommonJS to ESM (for any CJS dependencies) 
+    commonjs(),
+    // Compile TypeScript
+    typescript({
+      tsconfig: './tsconfig.json',
+      sourceMap: true,
+      declaration: false, // We'll use tsc for declarations
+    }),
+  ],
+};

package/src/index.ts

@@ -0,0 +1,420 @@
+import got, { OptionsOfTextResponseBody, Response, RequestError } from 'got';
+import type { IProtocolPlugin, Request, ExecutionContext, ProtocolResponse, ValidationResult, ValidationError, RuntimeOptions, ILogger } from '@apiquest/types';
+import { HttpProxyAgent, HttpsProxyAgent } from 'hpagent';
+
+interface BodyObject {
+  mode?: string;
+  raw?: string;
+  urlencoded?: Array<{ key?: string; value?: unknown; disabled?: boolean }>;
+  formdata?: Array<{ key?: string; value?: unknown; disabled?: boolean }>;
+  [key: string]: unknown;
+}
+
+// Helper functions for string validation
+function isNullOrEmpty(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value === '';
+}
+
+function isNullOrWhitespace(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value.trim() === '';
+}
+
+/**
+ * Parse proxy configuration from environment variables
+ * Platform-agnostic: checks both uppercase and lowercase variants
+ */
+function getProxyFromEnv(targetUrl: string): { host: string; port: number; auth?: { username: string; password: string } } | null {
+  // Check both uppercase and lowercase variants (platform-agnostic)
+  const HTTP_PROXY = process.env.HTTP_PROXY ?? process.env.http_proxy;
+  const HTTPS_PROXY = process.env.HTTPS_PROXY ?? process.env.https_proxy;
+  
+  // Choose proxy based on target URL protocol
+  const proxyUrl = targetUrl.startsWith('https:') ? (HTTPS_PROXY ?? HTTP_PROXY) : HTTP_PROXY;
+  
+  if (proxyUrl === undefined || proxyUrl === '') {
+    return null;
+  }
+  
+  try {
+    const parsed = new URL(proxyUrl);
+    return {
+      host: parsed.hostname,
+      port: (parsed.port !== '' ? parseInt(parsed.port) : (parsed.protocol === 'https:' ? 443 : 80)),
+      auth: parsed.username !== '' ? {
+        username: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password)
+      } : undefined
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if host should bypass proxy based on NO_PROXY env var
+ */
+function shouldBypassProxy(targetUrl: string): boolean {
+  const NO_PROXY = process.env.NO_PROXY ?? process.env.no_proxy;
+  
+  if (NO_PROXY === undefined || NO_PROXY === '') {
+    return false;
+  }
+  
+  const bypassList = NO_PROXY.split(',').map(s => s.trim());
+  const parsed = new URL(targetUrl);
+  
+  return bypassList.some(pattern => {
+    return parsed.hostname === pattern || 
+           (pattern.startsWith('*.') && parsed.hostname.endsWith(pattern.slice(1)));
+  });
+}
+
+export const httpPlugin: IProtocolPlugin = {
+  name: 'HTTP Client',
+  version: '1.0.0',
+  description: 'HTTP/HTTPS protocol support for REST APIs',
+  
+  // What protocols this plugin provides
+  protocols: ['http'],
+
+  // Supported authentication types
+  supportedAuthTypes: ['bearer', 'basic', 'oauth2', 'apikey', 'digest', 'ntlm'],
+  
+  // Accept additional auth plugins beyond the listed types
+  strictAuthList: false,
+
+  // Data schema for HTTP requests
+  dataSchema: {
+    type: 'object',
+    required: ['method', 'url'],
+    properties: {
+      method: {
+        type: 'string',
+        enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
+        description: 'HTTP method'
+      },
+      url: {
+        type: 'string',
+        description: 'Request URL'
+      },
+      headers: {
+        type: 'object',
+        description: 'HTTP headers',
+        additionalProperties: { type: 'string' }
+      },
+      body: {
+        description: 'Request body (string or structured object)',
+        oneOf: [
+          { type: 'string' },
+          { type: 'object' }
+        ]
+      }
+    }
+  },
+
+  // Options schema for runtime configuration
+  optionsSchema: {
+    keepAlive: {
+      type: 'boolean',
+      default: true,
+      description: 'Keep TCP connections alive between requests'
+    },
+    timeout: {
+      type: 'number',
+      default: 30000,
+      description: 'Request timeout in milliseconds'
+    },
+    followRedirects: {
+      type: 'boolean',
+      default: true,
+      description: 'Follow HTTP redirects automatically'
+    },
+    maxRedirects: {
+      type: 'number',
+      default: 5,
+      description: 'Maximum number of redirects to follow'
+    },
+    validateCertificates: {
+      type: 'boolean',
+      default: true,
+      description: 'Validate SSL/TLS certificates'
+    }
+  },
+
+  async execute(request: Request, context: ExecutionContext, options: RuntimeOptions, emitEvent?: (eventName: string, eventData: unknown) => Promise<void>, logger?: ILogger): Promise<ProtocolResponse> {
+    const startTime = Date.now();
+    const url = String(request.data.url ?? '');
+
+    try {
+      // Request configuration
+      const method = String(request.data.method ?? 'GET');
+      const headers: Record<string, string> = typeof request.data.headers === 'object' && request.data.headers !== null
+        ? Object.fromEntries(
+            Object.entries(request.data.headers as Record<string, unknown>).map(([k, v]) => [k, String(v)])
+          )
+        : {};
+      const body: unknown = request.data.body;
+
+      if (isNullOrWhitespace(url)) {
+        logger?.error('HTTP request missing URL');
+        throw new Error('URL is required for HTTP requests');
+      }
+
+      const httpOptions: Record<string, unknown> = (options.plugins?.http as Record<string, unknown> | null | undefined) ?? {};
+      const httpTimeout = typeof httpOptions.timeout === 'number' ? httpOptions.timeout : null;
+      const timeout = options.timeout?.request ?? httpTimeout ?? 60000;
+      const httpFollowRedirects = typeof httpOptions.followRedirects === 'boolean' ? httpOptions.followRedirects : null;
+      const followRedirects = options.followRedirects ?? httpFollowRedirects ?? true;
+      const httpMaxRedirects = typeof httpOptions.maxRedirects === 'number' ? httpOptions.maxRedirects : null;
+      const maxRedirects = options.maxRedirects ?? httpMaxRedirects ?? 5;
+      const httpValidateCerts = typeof httpOptions.validateCertificates === 'boolean' ? httpOptions.validateCertificates : null;
+      const validateCerts = options.ssl?.validateCertificates ?? httpValidateCerts ?? true;
+
+      logger?.debug('HTTP request options resolved', {
+        method,
+        timeout,
+        followRedirects,
+        maxRedirects,
+        validateCerts
+      });
+
+      // Cookie handling
+      const cookieHeader = context.cookieJar.getCookieHeader(url);
+      if (cookieHeader !== null) {
+        headers['Cookie'] = cookieHeader;
+        logger?.trace('Cookie header applied', { url });
+      }
+
+      const gotOptions: OptionsOfTextResponseBody = {
+        method: method.toUpperCase() as 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS',
+        headers: { ...headers },
+        throwHttpErrors: false,
+        timeout: { request: timeout },
+        followRedirect: followRedirects,
+        allowGetBody: true,
+        https: {
+          rejectUnauthorized: validateCerts,
+          certificate: options.ssl?.clientCertificate?.cert,
+          key: options.ssl?.clientCertificate?.key,
+          passphrase: options.ssl?.clientCertificate?.passphrase,
+          certificateAuthority: options.ssl?.ca
+        },
+        signal: context.abortSignal as AbortSignal | undefined
+      };
+
+      // Body encoding
+      if (body !== undefined && body !== null && body !== '') {
+        if (typeof body === 'string') {
+          gotOptions.body = body;
+        } else if (typeof body === 'object') {
+          const bodyObj = body as BodyObject;
+
+          if (bodyObj.mode === 'none') {
+            logger?.trace('HTTP body mode set to none; skipping body');
+          } else if (bodyObj.mode === 'raw' && typeof bodyObj.raw === 'string') {
+            gotOptions.body = bodyObj.raw;
+          } else if (bodyObj.mode === 'urlencoded' && Array.isArray(bodyObj.urlencoded)) {
+            const params = new URLSearchParams();
+            bodyObj.urlencoded.forEach((item: { key?: string; value?: unknown; disabled?: boolean }) => {
+              if (typeof item.key === 'string' && item.value !== undefined) {
+                params.append(item.key, String(item.value));
+              }
+            });
+            gotOptions.body = params.toString();
+            gotOptions.headers ??= {};
+            gotOptions.headers['content-type'] = 'application/x-www-form-urlencoded';
+          } else if (bodyObj.mode === 'formdata' && Array.isArray(bodyObj.formdata)) {
+            gotOptions.json = bodyObj;
+          } else {
+            gotOptions.json = bodyObj;
+          }
+        }
+      }
+
+      // Proxy setup
+      let proxyConfig = options.proxy;
+
+      if ((proxyConfig?.host === undefined) && shouldBypassProxy(url) === false) {
+        const envProxy = getProxyFromEnv(url);
+        if (envProxy !== null) {
+          proxyConfig = {
+            enabled: true,
+            host: envProxy.host,
+            port: envProxy.port,
+            auth: envProxy.auth
+          };
+        }
+      }
+
+      if (proxyConfig?.enabled !== false && proxyConfig?.host !== undefined && proxyConfig.host !== '') {
+        const targetUrl = new URL(url);
+        const explicitBypass = proxyConfig.bypass?.some(pattern => {
+          return targetUrl.hostname === pattern ||
+                 (pattern.startsWith('*.') && targetUrl.hostname.endsWith(pattern.slice(1)));
+        }) ?? false;
+
+        const envBypass = shouldBypassProxy(url);
+        const shouldBypass = explicitBypass || envBypass;
+
+        if (shouldBypass === false) {
+          const proxyAuth = (proxyConfig.auth !== undefined && proxyConfig.auth !== null)
+            ? `${encodeURIComponent(proxyConfig.auth.username)}:${encodeURIComponent(proxyConfig.auth.password)}@`
+            : '';
+
+          const fullProxyUrl = `http://${proxyAuth}${proxyConfig.host}:${proxyConfig.port}`;
+
+          gotOptions.agent = {
+            http: new HttpProxyAgent({
+              keepAlive: true,
+              keepAliveMsecs: 1000,
+              maxSockets: 256,
+              maxFreeSockets: 256,
+              scheduling: 'lifo',
+              proxy: fullProxyUrl
+            }),
+            https: new HttpsProxyAgent({
+              keepAlive: true,
+              keepAliveMsecs: 1000,
+              maxSockets: 256,
+              maxFreeSockets: 256,
+              scheduling: 'lifo',
+              proxy: fullProxyUrl
+            })
+          };
+        }
+      }
+
+      // Dispatch
+      logger?.debug('HTTP request dispatch', { url, method });
+      const response: Response = await got(url, gotOptions);
+      const duration = Date.now() - startTime;
+
+      // Response normalization
+      const normalizedHeaders: Record<string, string | string[]> = {};
+      if (typeof response.headers === 'object' && response.headers !== null) {
+        Object.entries(response.headers).forEach(([key, value]) => {
+          if (Array.isArray(value)) {
+            normalizedHeaders[key.toLowerCase()] = value.map(item => String(item));
+          } else if (value !== undefined && value !== null) {
+            normalizedHeaders[key.toLowerCase()] = String(value);
+          }
+        });
+      }
+
+      if (normalizedHeaders['set-cookie'] !== undefined) {
+        context.cookieJar.store(normalizedHeaders['set-cookie'], url);
+        logger?.trace('Cookies stored from response', { url });
+      }
+
+      logger?.debug('HTTP response received', { status: response.statusCode, duration });
+
+      return {
+        status: response.statusCode,
+        statusText: (response.statusMessage !== null && response.statusMessage !== undefined && response.statusMessage.length > 0) ? response.statusMessage : '',
+        headers: normalizedHeaders,
+        body: String(response.body),
+        duration,
+      };
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      const error = err as RequestError;
+
+      if (error instanceof RequestError && error.name === 'AbortError') {
+        logger?.warn('HTTP request aborted', { url, duration });
+        return {
+          status: 0,
+          statusText: 'Aborted',
+          body: '',
+          headers: {},
+          duration,
+          error: 'Request aborted'
+        };
+      }
+
+      if (error instanceof RequestError) {
+        if (error.response !== undefined) {
+          const normalizedHeaders: Record<string, string | string[]> = {};
+          if (typeof error.response.headers === 'object' && error.response.headers !== null) {
+            Object.entries(error.response.headers).forEach(([key, value]) => {
+              if (Array.isArray(value)) {
+                normalizedHeaders[key.toLowerCase()] = value.map(item => String(item));
+              } else if (value !== undefined && value !== null) {
+                normalizedHeaders[key.toLowerCase()] = String(value);
+              }
+            });
+          }
+
+          if (normalizedHeaders['set-cookie'] !== undefined) {
+            context.cookieJar.store(normalizedHeaders['set-cookie'], url);
+            logger?.trace('Cookies stored from error response', { url });
+          }
+
+          logger?.debug('HTTP error response received', { status: error.response.statusCode, duration });
+
+          return {
+            status: error.response.statusCode,
+            statusText: (error.response.statusMessage !== null && error.response.statusMessage !== undefined && error.response.statusMessage.length > 0) ? error.response.statusMessage : '',
+            headers: normalizedHeaders,
+            body: String(error.response.body),
+            duration,
+          };
+        } else {
+          logger?.warn('HTTP network error', { message: error.message, duration });
+          return {
+            status: 0,
+            statusText: 'Network Error',
+            headers: {},
+            body: '',
+            duration,
+            error: !isNullOrEmpty(error.message) ? error.message : 'Network request failed'
+          };
+        }
+      }
+
+      logger?.error('HTTP unexpected error', { error: err instanceof Error ? err.message : String(err), duration });
+      return {
+        status: 0,
+        statusText: 'Error',
+        headers: {},
+        body: '',
+        duration,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  },
+
+  validate(request: Request, options: RuntimeOptions): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // Check URL
+    if (typeof request.data.url !== 'string' || isNullOrWhitespace(request.data.url)) {
+      errors.push({
+        message: 'URL is required',
+        location: '',
+        source: 'protocol'
+      });
+    }
+
+    // Check method
+    const method = (typeof request.data.method === 'string' && !isNullOrEmpty(request.data.method)) ? request.data.method.toUpperCase() : 'GET';
+    const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+    if (!validMethods.includes(method)) {
+      errors.push({
+        message: `Invalid HTTP method: ${method}`,
+        location: '',
+        source: 'protocol'
+      });
+    }
+
+    if (errors.length > 0) {
+      return {
+        valid: false,
+        errors
+      };
+    }
+
+    return { valid: true };
+  }
+};
+
+export default httpPlugin;

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["tests/**/*"],
+  "exclude": []
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});