Protocol Handlers

// Required Node.js imports for the types below
import { Readable } from 'stream';
import { Stats } from 'fs';
import http from 'http';

/**
 * Handler for data: URIs
 * @param parsed - Parsed URL object
 * @param opts - Data protocol options
 * @returns Promise resolving to DataReadable stream
 */
const data: GetUriProtocol<DataOptions>;

interface DataOptions {
  /** Previous DataReadable stream for cache validation */
  cache?: DataReadable;
}

/**
 * Readable stream for data URIs with hash-based caching
 */
class DataReadable extends Readable {
  /** SHA1 hash of the data URI for cache validation */
  hash?: string;
  constructor(hash: string, buf: Buffer);
}

import { getUri } from "get-uri";

// Basic data URI
const stream = await getUri('data:text/plain;base64,SGVsbG8gV29ybGQ=');

// With caching
const cachedStream = await getUri(
  'data:text/plain;base64,SGVsbG8gV29ybGQ=',
  { cache: previousStream }
);

/**
 * Handler for file: URIs  
 * @param parsed - Parsed URL object
 * @param opts - File protocol options
 * @returns Promise resolving to FileReadable stream
 */
const file: GetUriProtocol<FileOptions>;

interface FileOptions {
  /** Previous FileReadable stream for cache validation */
  cache?: FileReadable;
  /** File access flags (default: 'r') */
  flags?: string;
  /** File mode (default: 438/0666) */
  mode?: number;
  /** Start position for reading (byte offset) */
  start?: number;
  /** End position for reading (byte offset) */
  end?: number;
  /** High water mark for the stream buffer */
  highWaterMark?: number;
  /** Character encoding for the stream */
  encoding?: BufferEncoding;
}

/**
 * Readable stream for file URIs with file stats caching
 */
interface FileReadable extends Readable {
  /** File system stats for cache validation */
  stat?: Stats; // from 'fs' module
}

import { getUri } from "get-uri";

// Basic file access
const stream = await getUri('file:///Users/user/document.txt');

// With custom options
const streamWithOptions = await getUri('file:///path/to/file.txt', {
  flags: 'r',
  mode: 0o644,
  cache: previousFileStream
});

/**
 * Handler for ftp: URIs
 * @param parsed - Parsed URL object  
 * @param opts - FTP protocol options
 * @returns Promise resolving to FTPReadable stream
 */
const ftp: GetUriProtocol<FTPOptions>;

interface FTPOptions {
  /** Previous FTPReadable stream for cache validation */
  cache?: FTPReadable;
  /** FTP server host */
  host?: string;
  /** FTP server port (default: 21) */
  port?: number;
  /** Username for authentication */
  user?: string;
  /** Password for authentication */
  password?: string;
  /** Use secure FTP (FTPS) */
  secure?: boolean;
  /** Additional FTP client options */
  [key: string]: any;
}

/**
 * Readable stream for FTP URIs with last-modified caching
 */
interface FTPReadable extends Readable {
  /** Last modified date for cache validation */
  lastModified?: Date;
}

import { getUri } from "get-uri";

// Basic FTP access
const stream = await getUri('ftp://ftp.example.com/path/to/file.txt');

// With authentication
const authStream = await getUri('ftp://user:pass@ftp.example.com/file.txt');

// With custom options
const customStream = await getUri('ftp://ftp.example.com/file.txt', {
  host: 'ftp.example.com',
  port: 21,
  user: 'username',
  password: 'password',
  cache: previousFtpStream
});

/**
 * Handler for http: URIs
 * @param parsed - Parsed URL object
 * @param opts - HTTP protocol options  
 * @returns Promise resolving to HttpReadable stream
 */
const http: GetUriProtocol<HttpOptions>;

interface HttpOptions {
  /** Previous HttpReadable stream for cache validation */
  cache?: HttpReadable;
  /** HTTP/HTTPS module to use (for protocol switching) */
  http?: any;
  /** Array of redirect responses */
  redirects?: HttpReadable[];
  /** Maximum redirects allowed (default: 5) */
  maxRedirects?: number;
  /** Request headers */
  headers?: { [key: string]: string };
  /** Request method (default: 'GET') */
  method?: string;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** TLS/SSL certificate */
  cert?: string | Buffer;
  /** TLS/SSL private key */
  key?: string | Buffer;
  /** Certificate authority */
  ca?: string | Buffer | Array<string | Buffer>;
  /** Reject unauthorized certificates (default: true) */
  rejectUnauthorized?: boolean;
}

/**
 * Readable stream for HTTP URIs with response metadata
 */
interface HttpReadable extends Readable, HttpReadableProps {}

interface HttpReadableProps {
  /** Response date timestamp for cache calculations */
  date?: number;
  /** Parsed URL object */
  parsed?: URL;
  /** Array of redirect responses leading to this response */
  redirects?: HttpReadable[];
}

/**
 * HTTP response message with additional metadata
 */
interface HttpIncomingMessage extends http.IncomingMessage, HttpReadableProps {} // from 'http' module

import { getUri } from "get-uri";

// Basic HTTP request
const stream = await getUri('http://httpbin.org/json');

// With custom headers
const customStream = await getUri('http://api.example.com/data', {
  headers: {
    'Authorization': 'Bearer token',
    'User-Agent': 'MyApp/1.0'
  }
});

// With redirect control
const redirectStream = await getUri('http://example.com/redirect', {
  maxRedirects: 10,
  cache: previousHttpStream
});

/**
 * Handler for https: URIs
 * @param parsed - Parsed URL object
 * @param opts - HTTPS protocol options (same as HTTP)
 * @returns Promise resolving to HttpReadable stream  
 */
const https: GetUriProtocol<HttpOptions>;

import { getUri } from "get-uri";

// Basic HTTPS request
const stream = await getUri('https://httpbin.org/json');

// With custom TLS options
const tlsStream = await getUri('https://api.example.com/secure', {
  rejectUnauthorized: false,
  cert: certificateBuffer,
  key: privateKeyBuffer
});

/**
 * Registry mapping protocol names to their handler functions
 */
const protocols: {
  data: GetUriProtocol<DataOptions>;
  file: GetUriProtocol<FileOptions>;
  ftp: GetUriProtocol<FTPOptions>;
  http: GetUriProtocol<HttpOptions>;
  https: GetUriProtocol<HttpOptions>;
};

/**
 * Union type of all supported protocol names
 */
type Protocols = typeof protocols;