Drivers

A driver is responsible for executing a single request and returning a result. Each target in your config specifies a type that selects the driver. All drivers map their results to HTTP-like status codes so the engine’s error classifier, backoff, and metrics work uniformly.

auth block link

Any target (or target_defaults) can include an auth block to attach credentials to each request. The http and websocket drivers honour it; SFTP uses credentials from its sftp block; other drivers silently ignore it.

targets:
  - url: "https://api.example.com/data"
    type: http
    auth:
      type: bearer
      token_env: API_TOKEN       # resolved from environment at dispatch time

Auth types:

Token values are resolved at dispatch time — if the env var is unset when a request fires, the result carries an error and no request is made.

Shared credentials via target_defaults:

target_defaults:
  auth:
    type: bearer
    token_env: API_TOKEN

targets_file: "config/targets.txt"

All file-loaded targets inherit the shared auth. Inline targets can override or omit it.

http link

Sends an HTTP/HTTPS request using Go’s standard net/http client.

targets:
  - url: "https://example.com/api"
    weight: 5
    type: http
    http:
      method: GET                        # GET | POST | PUT | DELETE | ...
      headers:
        User-Agent: "Mozilla/5.0 ..."
        Accept: "application/json"
      body: '{"key":"value"}'            # optional request body (string)
      timeout_s: 15                      # per-request timeout in seconds
      allow_cross_host_redirects: false  # opt in to follow redirects to another host

Note: HTTP header map keys are lowercased by the YAML parser (e.g. User-Agent is stored as user-agent). This is standard YAML behaviour.

Non-standard ports: include the port directly in the URL — Go’s net/http client handles it natively:

- url: "http://internal-api.example.com:8080/health"
  type: http
- url: "https://staging.example.com:8443/api"
  type: http

browser link

Loads a page in a headless Chromium instance via chromedp. Each task spawns its own ExecAllocator — no shared browser state — which prevents memory accumulation across long runs.

targets:
  - url: "https://news.ycombinator.com"
    weight: 3
    type: browser
    browser:
      scroll: true                    # scroll to mid-page then bottom
      wait_for_selector: "#hnmain"    # CSS selector to wait for before returning
      timeout_s: 30                   # page load timeout in seconds

Prerequisite: Chrome or Chromium must be installed on the machine running sendit.

Use max_browser_workers in limits to cap concurrent browser instances independently of the global worker pool:

limits:
  max_workers: 4
  max_browser_workers: 1   # at most 1 Chrome instance at a time

dns link

Resolves a hostname using miekg/dns directly — no system resolver involved. DNS RCODEs are mapped to HTTP-like status codes:

targets:
  - url: "example.com"
    weight: 3
    type: dns
    dns:
      resolver: "8.8.8.8:53"    # DNS server address
      record_type: A             # A | AAAA | MX | TXT | CNAME | ...

The resolver field is always host:port, so non-standard DNS ports are supported directly:

dns:
  resolver: "192.168.1.1:5353"   # custom resolver on non-standard port
  record_type: A

websocket link

Opens a WebSocket connection using coder/websocket, optionally sends messages, and holds the connection open for a configurable duration.

targets:
  - url: "wss://stream.example.com/feed"
    weight: 2
    type: websocket
    websocket:
      duration_s: 30                            # hold connection for this many seconds
      send_messages: ['{"type":"subscribe"}']   # messages to send on connect
      expect_messages: 1                        # wait to receive this many messages

Non-standard ports: include the port in the URL:

- url: "wss://stream.example.com:9443/feed"
  type: websocket

grpc link

Executes a unary gRPC call using google.golang.org/grpc. No .proto files are required — the driver uses server reflection to discover request and response types at runtime, then marshals the JSON body to protobuf automatically.

targets:
  - url: grpc://localhost:50051/helloworld.Greeter/SayHello
    weight: 10
    type: grpc
    grpc:
      body: '{"name": "world"}'   # JSON-encoded request (optional — defaults to empty message)
      timeout_s: 15               # per-call timeout in seconds
      tls: false                  # force TLS even when scheme is grpc://
      insecure: false             # skip TLS certificate verification

URL scheme selects transport security:

gRPC status codes are mapped to HTTP-like status codes so the engine’s backoff and error classifier work uniformly:

Prerequisite: the gRPC server must have the server reflection service enabled. Most frameworks enable it via a single line (e.g. reflection.Register(s) in Go). If reflection is not available, the driver returns an error immediately.

Connection and descriptor caching: connections and method descriptors are cached per address+TLS mode. Reflection is called only on the first request to each method; subsequent calls reuse the cached descriptor.

# Multiple gRPC targets on the same server — connection is shared
targets:
  - url: grpc://api.example.com:50051/user.UserService/GetUser
    type: grpc
    weight: 8
    grpc:
      body: '{"user_id": "u-123"}'
  - url: grpc://api.example.com:50051/user.UserService/ListUsers
    type: grpc
    weight: 2
    grpc:
      body: '{}'

sftp link

Executes SFTP operations over SSH using github.com/pkg/sftp and golang.org/x/crypto/ssh.

targets:
  - url: sftp://sftp.example.com/uploads/test.bin
    weight: 2
    type: sftp
    sftp:
      username: testuser
      password: secret
      insecure: false
      operation: upload
      file_size_min_bytes: 1024
      file_size_max_bytes: 1048576
      allowed_host_key_types: [ssh-ed25519]

Operations:

Payload sizing: set file_size_bytes for a fixed upload size, or set file_size_min_bytes and file_size_max_bytes for a random size chosen per request. If no size is set, uploads use a small default payload. Set eicar: true only when you intentionally want antivirus or malware-scanning infrastructure to see the EICAR standard test string.

Host keys: by default, SFTP verifies host keys against ~/.ssh/known_hosts. Set insecure: true only for trusted lab or ephemeral hosts where pinning is impractical.

Algorithm policy: use the allowed_* lists to enforce SSH policy. If the server cannot negotiate an allowed algorithm, the result is mapped to 502.

sftp:
  allowed_ciphers: [aes256-gcm@openssh.com, chacha20-poly1305@openssh.com]
  allowed_kex: [curve25519-sha256]
  allowed_host_key_types: [ssh-ed25519]
  allowed_macs: [hmac-sha2-256-etm@openssh.com]

SFTP status codes are mapped to HTTP-like status codes:

JSONL metadata: SFTP results include sftp_server_version, sftp_host_key_type, sftp_host_key_fp, and sftp_auth_methods when available. list results also include sftp_entry_count.