or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdhttp-client.mdindex.mdproxy-support.md
tile.json

tessl/npm-actions--http-client

A lightweight HTTP client optimized for building actions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@actions/http-client@2.2.x

To install, run

npx @tessl/cli install tessl/npm-actions--http-client@2.2.0

index.mddocs/

@actions/http-client

@actions/http-client is a lightweight HTTP client optimized for building GitHub Actions with TypeScript support. It provides async/await patterns, built-in proxy support that integrates seamlessly with GitHub Actions runners, multiple authentication methods, automatic redirect handling, and comprehensive error handling that returns response objects rather than throwing exceptions for HTTP status codes.

Package Information

  • Package Name: @actions/http-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @actions/http-client

Core Imports

import { HttpClient, HttpClientResponse } from "@actions/http-client";

For authentication handlers:

import { 
  BasicCredentialHandler, 
  BearerCredentialHandler, 
  PersonalAccessTokenCredentialHandler 
} from "@actions/http-client/lib/auth";

CommonJS:

const { HttpClient } = require("@actions/http-client");
const { BasicCredentialHandler } = require("@actions/http-client/lib/auth");

Basic Usage

import { HttpClient } from "@actions/http-client";

// Create client with user agent
const client = new HttpClient("my-action/1.0");

// Make GET request
const response = await client.get("https://api.github.com/user");
console.log(response.message.statusCode); // 200
const body = await response.readBody();

// Make JSON requests with type safety
interface User {
  login: string;
  id: number;
}

const typedResponse = await client.getJson<User>("https://api.github.com/user");
if (typedResponse.result) {
  console.log(typedResponse.result.login);
}

Architecture

The @actions/http-client is built around several key components:

  • HttpClient Class: Main client providing HTTP methods with automatic proxy detection, redirect handling, and retry logic
  • Response Handling: HttpClientResponse class for reading response bodies as strings or buffers
  • Authentication System: Pluggable request handlers for Basic, Bearer, and PAT authentication
  • Proxy Integration: Automatic proxy detection based on environment variables with bypass rules
  • Error Handling: HttpClientError class that includes status codes and doesn't throw for HTTP errors
  • Type Safety: Full TypeScript integration with generic support for JSON operations

Capabilities

HTTP Client

Core HTTP client functionality providing all standard HTTP methods with automatic proxy detection, redirect handling, and retry logic.

class HttpClient {
  constructor(
    userAgent?: string, 
    handlers?: RequestHandler[], 
    requestOptions?: RequestOptions
  );
  
  // HTTP Methods
  get(requestUrl: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  post(requestUrl: string, data: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  put(requestUrl: string, data: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  patch(requestUrl: string, data: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  del(requestUrl: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  head(requestUrl: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  options(requestUrl: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  
  // JSON Methods
  getJson<T>(requestUrl: string, additionalHeaders?: http.OutgoingHttpHeaders): Promise<TypedResponse<T>>;
  postJson<T>(requestUrl: string, obj: any, additionalHeaders?: http.OutgoingHttpHeaders): Promise<TypedResponse<T>>;
  putJson<T>(requestUrl: string, obj: any, additionalHeaders?: http.OutgoingHttpHeaders): Promise<TypedResponse<T>>;
  patchJson<T>(requestUrl: string, obj: any, additionalHeaders?: http.OutgoingHttpHeaders): Promise<TypedResponse<T>>;
  
  // Stream and Raw Methods
  sendStream(verb: string, requestUrl: string, stream: NodeJS.ReadableStream, additionalHeaders?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  request(verb: string, requestUrl: string, data: string | NodeJS.ReadableStream | null, headers?: http.OutgoingHttpHeaders): Promise<HttpClientResponse>;
  
  // Agent Management
  getAgent(serverUrl: string): http.Agent;
  dispose(): void;
}

class HttpClientResponse {
  constructor(message: http.IncomingMessage);
  message: http.IncomingMessage;
  readBody(): Promise<string>;
  readBodyBuffer?(): Promise<Buffer>;
}

HTTP Client

Authentication

Authentication handler system supporting Basic, Bearer token, and Personal Access Token authentication with extensible handler interface.

interface RequestHandler {
  prepareRequest(options: http.RequestOptions): void;
  canHandleAuthentication(response: HttpClientResponse): boolean;
  handleAuthentication(
    httpClient: HttpClient, 
    requestInfo: RequestInfo, 
    data: string | NodeJS.ReadableStream | null
  ): Promise<HttpClientResponse>;
}

class BasicCredentialHandler implements RequestHandler {
  constructor(username: string, password: string);
}

class BearerCredentialHandler implements RequestHandler {
  constructor(token: string);
}

Authentication

Proxy Support

Proxy detection and configuration based on environment variables with bypass rules for local addresses.

function getProxyUrl(serverUrl: string): string;

Proxy Support

Utility Functions

General utility functions for HTTP operations.

function isHttps(requestUrl: string): boolean;

Core Types

interface RequestOptions {
  headers?: http.OutgoingHttpHeaders;
  socketTimeout?: number;
  ignoreSslError?: boolean;
  allowRedirects?: boolean;
  allowRedirectDowngrade?: boolean;
  maxRedirects?: number;
  maxSockets?: number;
  keepAlive?: boolean;
  deserializeDates?: boolean;
  allowRetries?: boolean;
  maxRetries?: number;
}

interface TypedResponse<T> {
  statusCode: number;
  result: T | null;
  headers: http.IncomingHttpHeaders;
}

interface RequestInfo {
  options: http.RequestOptions;
  parsedUrl: URL;
  httpModule: typeof http | typeof https;
}

class HttpClientError extends Error {
  constructor(message: string, statusCode: number);
  statusCode: number;
  result?: any;
}

enum HttpCodes {
  OK = 200,
  MultipleChoices = 300,
  MovedPermanently = 301,
  ResourceMoved = 302,
  SeeOther = 303,
  NotModified = 304,
  UseProxy = 305,
  SwitchProxy = 306,
  TemporaryRedirect = 307,
  PermanentRedirect = 308,
  BadRequest = 400,
  Unauthorized = 401,
  PaymentRequired = 402,
  Forbidden = 403,
  NotFound = 404,
  MethodNotAllowed = 405,
  NotAcceptable = 406,
  ProxyAuthenticationRequired = 407,
  RequestTimeout = 408,
  Conflict = 409,
  Gone = 410,
  TooManyRequests = 429,
  InternalServerError = 500,
  NotImplemented = 501,
  BadGateway = 502,
  ServiceUnavailable = 503,
  GatewayTimeout = 504
}

enum Headers {
  Accept = 'accept',
  ContentType = 'content-type'
}

enum MediaTypes {
  ApplicationJson = 'application/json'
}