README
¶
Tracker Connections
The shared engine human uses to talk to every issue tracker and forge over the network. It handles signing in, building requests, and turning failures into clear messages, so every backend behaves consistently and safely.
- Authenticates with tokens, basic auth, or headers
- Builds correct request URLs per backend
- Talks to both REST and GraphQL APIs
- Rejects unsafe URLs to prevent attacks
- Keeps secrets out of error messages
- Caps response sizes against bad upstreams
- Applies per-request timeouts
- Produces clear, provider-specific error messages
Documentation
¶
Index ¶
- Constants
- func DecodeJSON(resp *http.Response, dest interface{}, contextArgs ...interface{}) error
- func ValidateURL(rawURL string) error
- type AuthFunc
- type Client
- func (c *Client) Do(ctx context.Context, method, path, rawQuery string, body io.Reader) (*http.Response, error)
- func (c *Client) DoGraphQL(ctx context.Context, graphqlPath, query string, variables map[string]any) (json.RawMessage, error)
- func (c *Client) DoWithContentType(ctx context.Context, method, path, rawQuery string, body io.Reader, ...) (*http.Response, error)
- func (c *Client) SetHTTPDoer(doer HTTPDoer)
- type ErrorFormatter
- type GraphQLError
- type GraphQLRequest
- type GraphQLResponse
- type HTTPDoer
- type Option
- func WithAuth(auth AuthFunc) Option
- func WithContentType(ct string) Option
- func WithErrorFormatter(ef ErrorFormatter) Option
- func WithHTTPDoer(doer HTTPDoer) Option
- func WithHeader(name, value string) Option
- func WithPathSanitizer(ps PathSanitizer) Option
- func WithProviderName(name string) Option
- func WithTimeout(d time.Duration) Option
- func WithURLBuilder(ub URLBuilder) Option
- type PathSanitizer
- type URLBuilder
Constants ¶
const DefaultTimeout = 30 * time.Second
DefaultTimeout is the HTTP client timeout applied when no custom HTTPDoer is provided.
const MaxResponseBodyBytes = 50 * 1024 * 1024 // 50 MiB
MaxResponseBodyBytes bounds the number of bytes DecodeJSON and DoGraphQL will read from a response body before returning an error. It's large enough for realistic JSON payloads but prevents an adversarial or misbehaving upstream from exhausting memory.
Variables ¶
This section is empty.
Functions ¶
func DecodeJSON ¶
DecodeJSON reads and decodes a JSON response body into dest, then closes the body. Response bodies are capped at MaxResponseBodyBytes so an oversized or adversarial upstream cannot exhaust memory. The context args are passed to errors.WrapWithDetails on decode failure.
func ValidateURL ¶
ValidateURL checks that rawURL is a valid HTTP(S) URL. This guards against SSRF by rejecting non-HTTP schemes. HTTP URLs are accepted but logged as insecure; prefer HTTPS.
Types ¶
type AuthFunc ¶
AuthFunc applies authentication to an outgoing HTTP request.
func BearerToken ¶
BearerToken returns an AuthFunc that sets a Bearer token Authorization header.
func HeaderAuth ¶
HeaderAuth returns an AuthFunc that sets a custom header for authentication.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a shared HTTP API client that handles URL construction, authentication, headers, and error handling. Client is not safe for concurrent modification. All configuration (including SetHTTPDoer) must be done before the first call to Do.
func (*Client) Do ¶
func (c *Client) Do(ctx context.Context, method, path, rawQuery string, body io.Reader) (*http.Response, error)
Do executes an HTTP request with the client's configuration.
func (*Client) DoGraphQL ¶
func (c *Client) DoGraphQL(ctx context.Context, graphqlPath, query string, variables map[string]any) (json.RawMessage, error)
DoGraphQL marshals a GraphQL request, posts it, and returns the data field.
func (*Client) DoWithContentType ¶
func (c *Client) DoWithContentType(ctx context.Context, method, path, rawQuery string, body io.Reader, contentType string) (*http.Response, error)
DoWithContentType executes an HTTP request with an explicit Content-Type, overriding the client's default for this single request.
func (*Client) SetHTTPDoer ¶
SetHTTPDoer replaces the HTTP client used for API requests.
type ErrorFormatter ¶
ErrorFormatter formats an HTTP error response into an error value.
type GraphQLError ¶
type GraphQLError struct {
Message string `json:"message"`
}
GraphQLError represents a single GraphQL error.
type GraphQLRequest ¶
type GraphQLRequest struct {
Query string `json:"query"`
Variables map[string]any `json:"variables,omitempty"`
}
GraphQLRequest is the standard GraphQL request body.
type GraphQLResponse ¶
type GraphQLResponse struct {
Data json.RawMessage `json:"data"`
Errors []GraphQLError `json:"errors,omitempty"`
}
GraphQLResponse is the standard GraphQL response envelope.
type HTTPDoer ¶
HTTPDoer abstracts HTTP request execution for testability and to decouple from the concrete *http.Client type.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithContentType ¶
WithContentType sets a Content-Type header on every request, regardless of whether a body is present. When empty (the default), Content-Type is set to "application/json" only when a body is provided.
func WithErrorFormatter ¶
func WithErrorFormatter(ef ErrorFormatter) Option
WithErrorFormatter sets a custom error formatter.
func WithHTTPDoer ¶
WithHTTPDoer sets the HTTP client used for requests.
func WithHeader ¶
WithHeader adds a header to every request.
func WithPathSanitizer ¶
func WithPathSanitizer(ps PathSanitizer) Option
WithPathSanitizer installs a function that transforms the request path before it is included in error details. Providers that embed sensitive values into the URL path should supply a sanitizer so failure paths don't surface the raw value in log output.
func WithProviderName ¶
WithProviderName sets the provider name used in error messages.
func WithTimeout ¶
WithTimeout sets the HTTP client timeout. Only effective when no custom HTTPDoer is provided via WithHTTPDoer.
func WithURLBuilder ¶
func WithURLBuilder(ub URLBuilder) Option
WithURLBuilder sets the URL construction strategy.
type PathSanitizer ¶
PathSanitizer transforms a request path before it is included in error details. Use it when the path may contain secrets that would otherwise appear verbatim in log output on transport or decode failures.
type URLBuilder ¶
URLBuilder constructs a full URL from a parsed base URL, path, and raw query string.
func ParsePathURL ¶
func ParsePathURL() URLBuilder
ParsePathURL returns a URLBuilder that parses the path as a URL to extract embedded query parameters. Used by Notion, Figma, and Telegram where the path may include query strings (e.g. "/v1/files/key?depth=1").
func RawPathURL ¶
func RawPathURL() URLBuilder
RawPathURL returns a URLBuilder that also sets u.RawPath to preserve percent-encoding in paths. Used by GitLab where project paths contain encoded slashes (e.g. "mygroup%2Fmyproject").
func StandardURL ¶
func StandardURL() URLBuilder
StandardURL returns a URLBuilder that sets u.Path and u.RawQuery directly. Used by Jira, GitHub, Azure DevOps, Shortcut, and Amplitude.
Source Files
Directories