clientsignals

package module
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

client-signals for Go

Go implementation of the shared client-signals contract.

Installation

go get github.com/superfly/client-signals/go

The package name is clientsignals:

import clientsignals "github.com/superfly/client-signals/go"

Usage

sig := clientsignals.DetectOnce()

header := http.Header{}
sig.ApplyHeaders(header)

To wrap an http.Client transport:

httpClient := &http.Client{
    Transport: sig.WrapTransport(http.DefaultTransport),
}

Use a custom header prefix with ApplyHeadersWithPrefix or WrapTransportWithPrefix:

sig.ApplyHeadersWithPrefix(header, "Acme")

API

  • Detect() Signals computes fresh signals.
  • DetectOnce() Signals computes and caches process-wide signals.
  • Signals.Operator() returns ci, agent, interactive, or unknown; precedence is in that order.
  • Signals.ApplyHeaders(http.Header) applies Fly-Client-* headers.
  • Signals.ApplyHeadersWithPrefix(http.Header, string) applies custom prefix headers.
  • Signals.WrapTransport(http.RoundTripper) wraps a transport and appends the User-Agent suffix.
  • Signals.WrapTransportWithPrefix(http.RoundTripper, string) wraps with a custom header prefix.
  • ClassifyRequestHeaders(http.Header) returns bounded operator and agent values for server-side metrics. Fly-Client-Interactive is the instrumentation sentinel; Parent is not used.
  • TrackedRoute(method, routeTemplate, requestPath, prefixes) selects configured route prefixes and returns a bounded "METHOD /route/{template}" label. Raw paths are never returned for unmatched requests.
  • NewRequestCounter(service, trackedRoutePrefixes) constructs the canonical fly_client_signals_requests_total Prometheus collector. Register it with the service's Prometheus registry and call Observe(request, routeTemplate) after routing.

Server-side request metrics

ClassifyRequestHeaders uses the following operator precedence: ci > agent > interactive > automated_unattributed. A missing or invalid Fly-Client-Interactive header produces uninstrumented.

Known agents retain their finite marker-table name. Valid sanitized self-declarations not in that table become other; missing or invalid agent values become none. This makes both fields suitable for metric labels without allowing caller-controlled cardinality.

The request counter owns the canonical metric name, help text, label order, route filtering, and request classification. The consuming service remains responsible for registering the collector and providing its bounded service name, tracked route prefixes, and router-owned route template.

The Go module lives under go/; consumers of the old root module path must update imports to github.com/superfly/client-signals/go.

Development

go test ./...
go build ./...
GOOS=linux GOARCH=amd64 go build ./...
GOOS=darwin GOARCH=arm64 go build ./...
GOOS=windows GOARCH=amd64 go build ./...

Documentation

Overview

Package clientsignals computes coarse, privacy-safe signals that help estimate whether a CLI process is being driven by a human or an AI agent.

This package is intentionally self-contained: no dependencies beyond the standard library and golang.org/x/sys (used for syscall-based parent-process lookup on Darwin/Windows), so it can be used standalone.

Index

Constants

View Source 
const (
	// RequestOperatorCI identifies instrumented requests made from CI.
	RequestOperatorCI = "ci"
	// RequestOperatorAgent identifies instrumented, non-CI requests with a
	// valid cooperative agent marker.
	RequestOperatorAgent = "agent"
	// RequestOperatorInteractive identifies instrumented, non-CI requests
	// whose stdout was attached to a terminal and had no agent marker.
	RequestOperatorInteractive = "interactive"
	// RequestOperatorAutomatedUnattributed identifies instrumented, non-CI,
	// non-interactive requests with no recognized agent marker.
	RequestOperatorAutomatedUnattributed = "automated_unattributed"
	// RequestOperatorUninstrumented identifies requests without a valid
	// Fly-Client-Interactive header.
	RequestOperatorUninstrumented = "uninstrumented"

	// RequestAgentNone is the bounded metric value used when no valid agent
	// marker was supplied.
	RequestAgentNone = "none"
	// RequestAgentOther is the bounded metric value used for valid sanitized
	// self-declarations that are not in the known marker table.
	RequestAgentOther = "other"
)
View Source 
const DefaultHeaderPrefix = "Fly"

DefaultHeaderPrefix is the header-name prefix WrapTransport uses when no other prefix is configured: "Fly", giving Fly-Client-Interactive, Fly-Client-Parent, etc. Callers outside Fly.io can use WrapTransportWithPrefix to substitute their own.

View Source 
const (
	// RequestMetricName is the canonical Prometheus counter name for requests
	// classified using client signals.
	RequestMetricName = "fly_client_signals_requests_total"
)

Variables

This section is empty.

Functions

func TrackedRoute added in v0.4.3 

func TrackedRoute(method, routeTemplate, requestPath string, prefixes []string) (string, bool)

TrackedRoute returns the bounded route metric label for a request and whether it should be recorded. A matched route template is preferred. For an unmatched request, requestPath is used only to determine whether the request targeted a tracked prefix and is never included in the returned label.

Types

type ClientSignalsTransport 

type ClientSignalsTransport struct {
	InnerTransport http.RoundTripper
	// contains filtered or unexported fields
}

ClientSignalsTransport wraps an http.RoundTripper, attaching the {prefix}-Client-* headers and appending the client-signals token to the existing User-Agent header on every outgoing request.

Construct one via Signals.WrapTransport or Signals.WrapTransportWithPrefix. RoundTrip does no detection work itself — it only applies the values already computed when the transport was built.

func (*ClientSignalsTransport) RoundTrip 

func (t *ClientSignalsTransport) RoundTrip(req *http.Request) (*http.Response, error)

type RequestClassification added in v0.4.3 

type RequestClassification struct {
	Operator string
	Agent    string
}

RequestClassification is the bounded, server-side interpretation of incoming client-signal headers. Operator and Agent are safe to use as metric labels.

func ClassifyRequestHeaders added in v0.4.3 

func ClassifyRequestHeaders(header http.Header) RequestClassification

ClassifyRequestHeaders returns bounded metric-label values for an incoming request. Fly-Client-Interactive is the instrumentation sentinel; Parent is deliberately ignored because parent-process lookup is not reliable enough for request classification.

CI takes precedence over agent, which takes precedence over interactive. Agent is still preserved for CI requests so aggregate metrics can expose the CI+agent overlap.

type RequestCounter added in v0.4.3 

type RequestCounter struct {
	// contains filtered or unexported fields
}

RequestCounter is the canonical Prometheus collector for requests classified using client signals. It is safe for concurrent use.

func NewRequestCounter added in v0.4.3 

func NewRequestCounter(service string, trackedRoutePrefixes []string) *RequestCounter

NewRequestCounter constructs the canonical client-signals request collector. The caller is responsible for registering it with a Prometheus registerer.

func (*RequestCounter) Collect added in v0.4.3 

func (c *RequestCounter) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*RequestCounter) Describe added in v0.4.3 

func (c *RequestCounter) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*RequestCounter) Observe added in v0.4.3 

func (c *RequestCounter) Observe(req *http.Request, routeTemplate string) bool

Observe records req when its matched route template or raw request path belongs to a configured prefix. routeTemplate should be the bounded template reported by the service's router, not the raw request path.

type Signals 

type Signals struct {
	// Interactive is true if the process's stdout appears to be attached to
	// a terminal.
	Interactive bool

	// Parent is a coarse bucket describing the immediate parent process.
	// Always one of "node", "python", "shell", or "other" — never a raw
	// process name.
	Parent string

	// Agent is the cooperative agent marker, e.g. "claude-code". Empty if no
	// agent was declared or detected.
	Agent string

	// AgentSource identifies how Agent was determined, e.g.
	// "env:FLY_INVOKED_BY" or "env:CLAUDECODE" — the matched variable name,
	// never its value. Empty if and only if Agent is empty.
	AgentSource string

	// CI is true when a CI environment is detected.
	CI bool
}

Signals is the set of coarse, privacy-safe traffic-classification signals computed once per process.

See docs/signals.md for the reasoning behind these fields, each one's known reliability caveats, and how they're meant to be combined — no single field here is sufficient on its own, and none should ever drive gating/enforcement decisions.

func Detect 

func Detect() Signals

Detect computes the current process's client signals fresh from the environment and file descriptors. It is pure and side-effect free (aside from reading process state); it does not cache its result — callers that want a single value for the lifetime of a process should cache it themselves.

func DetectOnce 

func DetectOnce() Signals

DetectOnce returns the process-wide signals, computed once via Detect and cached for the lifetime of the process. Detection involves a parent-process lookup and environment scanning, so callers should fetch this once (e.g. at client-construction time) and reuse the result rather than calling it per request.

func (Signals) ApplyHeaders 

func (s Signals) ApplyHeaders(header http.Header)

ApplyHeaders sets the Fly-Client-* headers on header directly, for callers that need to attach client signals to something other than an http.Request going through an http.RoundTripper — e.g. a WebSocket handshake's header, built and sent outside of net/http's Client/Transport machinery entirely. Uses DefaultHeaderPrefix ("Fly").

func (Signals) ApplyHeadersWithPrefix 

func (s Signals) ApplyHeadersWithPrefix(header http.Header, prefix string)

ApplyHeadersWithPrefix is like ApplyHeaders but lets callers outside Fly.io substitute their own header prefix, matching WrapTransportWithPrefix's prefix for the same Signals value.

func (Signals) Operator added in v0.4.2 

func (s Signals) Operator() string

Operator returns a single classification for the process's operator. Precedence: ci > agent > interactive > unknown.

This is a convenience for consumers that want one label describing who is driving the process. The raw fields (CI, Agent, Interactive) remain available for callers that need finer-grained logic.

func (Signals) WrapTransport 

func (s Signals) WrapTransport(inner http.RoundTripper) *ClientSignalsTransport

WrapTransport wraps inner in a *ClientSignalsTransport that attaches s to every request the returned transport forwards, using DefaultHeaderPrefix ("Fly-Client-*").

func (Signals) WrapTransportWithPrefix 

func (s Signals) WrapTransportWithPrefix(inner http.RoundTripper, prefix string) *ClientSignalsTransport

WrapTransportWithPrefix is like WrapTransport but lets callers outside Fly.io substitute their own header prefix (e.g. "Acme" for Acme-Client-Interactive, Acme-Client-Parent, ...) instead of the "Fly" default. prefix must not be empty.

Source Files

View all Source files

Directories

Path Synopsis
Command clientsignals prints the client signals that would be attached to outbound Fly API requests from the current process/environment.
 Command clientsignals prints the client signals that would be attached to outbound Fly API requests from the current process/environment.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.