or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

caching.md discovery.md download.md extraction.md index.md manifest.md versions.md

tile.json

Tool Download

HTTP-based tool downloading with authentication, retry logic, and robust error handling for reliable tool acquisition from remote URLs.

Capabilities

Download Tool

Downloads a tool from a URL and streams it into a file with automatic retry logic and error handling.

/**
 * Downloads a tool from a URL with retry logic and error handling
 * @param url - URL of the tool to download
 * @param dest - Optional destination path (auto-generated if not provided)
 * @param auth - Optional authorization header value
 * @param headers - Optional additional HTTP headers
 * @returns Promise resolving to the path of the downloaded tool
 */
function downloadTool(
  url: string,
  dest?: string,
  auth?: string,
  headers?: OutgoingHttpHeaders
): Promise<string>;

Usage Examples:

import { downloadTool } from "@actions/tool-cache";

// Basic download
const toolPath = await downloadTool("https://example.com/tool.zip");

// Download with custom destination
const toolPath = await downloadTool(
  "https://example.com/tool.zip",
  "/tmp/my-tool.zip"
);

// Download with authentication
const toolPath = await downloadTool(
  "https://api.github.com/repos/owner/repo/releases/assets/123",
  undefined,
  "token your-github-token"
);

// Download with custom headers
const toolPath = await downloadTool(
  "https://example.com/tool.zip",
  undefined,
  undefined,
  {
    "User-Agent": "MyAction/1.0",
    "Accept": "application/octet-stream"
  }
);

HTTP Error Handling

Custom error class for HTTP-related failures during downloads.

/**
 * Custom error class for HTTP download failures
 * Contains the HTTP status code that caused the error
 */
class HTTPError extends Error {
  constructor(readonly httpStatusCode: number | undefined);
}

Usage Examples:

import { downloadTool, HTTPError } from "@actions/tool-cache";

try {
  const toolPath = await downloadTool("https://example.com/nonexistent.zip");
} catch (error) {
  if (error instanceof HTTPError) {
    console.log(`HTTP Error: ${error.httpStatusCode}`);
    console.log(`Message: ${error.message}`);
  }
}

Implementation Details

Retry Behavior

Max Attempts: 3 by default
Retry Delay: Random delay between 10-20 seconds
Retryable Status: 5xx errors, 408 (timeout), 429 (rate limit)
Non-retryable: 4xx errors (except 408, 429)

Authentication

Basic Auth: Pass as auth parameter in format "username:password"
Bearer Token: Pass as auth parameter in format "token your-token"
Custom Headers: Use headers parameter for complex authentication schemes

Destination Handling

Auto-generated: Uses temp directory with random UUID if not specified
Directory Creation: Automatically creates parent directories
Overwrite Protection: Throws error if destination file already exists

Types

import { OutgoingHttpHeaders } from "http";

class HTTPError extends Error {
  readonly httpStatusCode: number | undefined;
  constructor(httpStatusCode: number | undefined);
}