Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (68 loc) · 4.65 KB

AGENTS.md

File metadata and controls

98 lines (68 loc) · 4.65 KB

fetch

This file provides guidance to AI agents when working with code in this repository. Keep this file updated after making changes.

Project Overview

fetch is a modern HTTP(S) client CLI written in Go. It features automatic response formatting (JSON, XML, YAML, HTML, CSS, CSV, protobuf, msgpack), image rendering in terminals, gRPC support with reflection/discovery and JSON-to-protobuf conversion, and authentication (Basic, Digest, Bearer, AWS SigV4).

The repository currently targets Go 1.26.1 in go.mod and GitHub Actions.

Common Commands

# Run all tests
go test -v ./...

# Run specific package tests
go test -v ./internal/format
go test -v ./integration

# Run a single test
go test -v ./internal/cli -run TestParseFlagAWS

# Build the binary
go build -o bin/fetch .

# Format code (CI will fail if not formatted)
gofmt -s -w .

# Verify modules
go mod tidy && go mod verify

# Run linter (CI uses staticcheck)
staticcheck ./...

# Format other files
prettier -w .

Architecture

Entry Point

main.go orchestrates the CLI: parses arguments via internal/cli, loads config via internal/config, and delegates to internal/fetch.Fetch().

Key Packages

  • internal/aws - AWS Signature V4 request signing.
  • internal/cli - Command-line argument parsing. App struct holds all parsed options.
  • internal/client - HTTP client wrapper with custom DNS resolver support.
  • internal/complete - Shell completion implementation.
  • internal/config - INI-format config file parsing with host-specific overrides.
  • internal/core - Shared types (Printer, Color, Format, HTTPVersion) and utilities.
  • internal/curl - Curl command parser for --from-curl flag. Tokenizes and parses curl command strings into an intermediate Result struct.
  • internal/digest - HTTP Digest Authentication challenge parsing and response computation (RFC 7616).
  • internal/fetch - Core HTTP request execution. fetch.go:Fetch() is the main entry point that builds requests, handles gRPC framing/reflection/discovery, and routes to formatters.
  • internal/fileutil - Shared file helpers, including cross-platform atomic replacement for temp-file write flows.
  • internal/format - Response body formatters (JSON, XML, YAML, HTML, CSS, CSV, msgpack, protobuf, SSE, NDJSON). Each formatter writes colored output to a Printer.
  • internal/grpc - gRPC framing, headers, and status code handling.
  • internal/image - Terminal image rendering (Kitty, iTerm2 inline, block-character fallback).
  • internal/image - Multipart form implementation.
  • internal/proto - Protocol buffer compilation and message handling for gRPC support.
  • internal/session - Named cookie sessions with persistent storage across invocations.
  • internal/update - Check for updates, download from Github, and self-update.
  • internal/ws - WebSocket message loop (read, write, bidirectional coordination).

Request Flow

  1. CLI args parsed (cli.Parse) → App struct
  2. Config file merged (config.GetFile)
  3. fetch.Request built from merged config
  4. If gRPC: load local proto schema or resolve it via reflection, setup descriptors, convert JSON→protobuf, frame message

Recent Notes

  • --grpc-list and --grpc-describe provide grpcurl-style discovery using reflection or local descriptor files.
  • --grpc now automatically tries gRPC reflection when no local schema is supplied.
  • Plaintext loopback gRPC servers are supported via h2c for both calls and discovery.
  1. HTTP client executes request
  2. Response formatted based on Content-Type and output to stdout (optionally via pager)

Retryable requests replay bodies by calling req.GetBody when available, reopening file-backed bodies directly when possible, and only spooling the original body to a temp file as a final fallback for one-shot streams. This avoids holding large uploads in memory and keeps retries working for closable bodies like *os.File.

Content Type Detection

internal/fetch/fetch.go:getContentType() maps MIME types to formatters. Supported types include JSON, XML, YAML, HTML, CSS, CSV, msgpack, protobuf, gRPC, SSE, NDJSON, and images.

Testing

  • Unit tests: *_test.go files alongside source in each package
  • Integration tests: integration/integration_test.go (comprehensive end-to-end tests)
  • CI runs tests on Ubuntu, macOS, and Windows

Docs

High level documentation exists in the README. All detailed documentation exists in the docs/ directory, and should be kept up-to-date with any code changes.

The --edit workflow accepts VISUAL/EDITOR values with flags and also preserves executable paths that contain spaces, even when those paths are not shell-quoted.