api

Documentation

Overview

Package api is the HTTP client the CLI uses to talk to the getdebug backend. Phase 1 stub — concrete methods land alongside the API routes.

Index

• Variables
• type Client
  • func New(baseURL, token string) (*Client, error)
  • func NewUnsafe(baseURL, token string) *Client
  • func (c *Client) Do(req *http.Request, out any) error
  • func (c *Client) PollOnce(ctx context.Context, deviceCode string) (*DeviceTokenResponse, error)
  • func (c *Client) PollUntilApproved(ctx context.Context, deviceCode string, interval time.Duration, ...) (*DeviceTokenResponse, error)
  • func (c *Client) RequestDeviceCode(ctx context.Context, clientName string) (*DeviceCodeResponse, error)
• type DeviceCodeRequest
• type DeviceCodeResponse
• type DeviceTokenResponse

Variables

var (
	ErrAuthorizationPending = errors.New("authorization_pending")
	ErrSlowDown             = errors.New("slow_down")
	ErrExpiredToken         = errors.New("expired_token")
	ErrAccessDenied         = errors.New("access_denied")
)

ErrAuthorizationPending is returned by PollToken on every "still waiting" poll. Callers loop until they see one of the terminal errors below or success.

var ErrInsecureBaseURL = errors.New("api base URL must be https:// (http allowed only for localhost/127.0.0.1)")

ErrInsecureBaseURL is returned when a non-https URL is supplied without a loopback host. The CLI's device-flow code and bearer token are too sensitive to send in the clear, and a phishing pitch ("use --api http://staging.attacker.example") otherwise lets the attacker collect freshly minted tokens.

Types

type Client

type Client struct {
	BaseURL string
	Token   string
	HTTP    *http.Client
}

Client holds the base URL + auth token for the getdebug API.

func New

func New(baseURL, token string) (*Client, error)

New returns a Client with sensible defaults.

Returns ErrInsecureBaseURL if baseURL is an http:// URL pointing at a non-loopback host. Callers that want the old "trust whatever URL" shape for tests can use NewUnsafe.

func NewUnsafe

func NewUnsafe(baseURL, token string) *Client

NewUnsafe skips the https check. Intended for unit tests that spin up a local httptest.Server. Do not use in production code paths.

func (*Client) Do

func (c *Client) Do(req *http.Request, out any) error

Do issues an HTTP request and decodes the envelope into out (if non-nil). Returns an error built from the envelope's error block on non-ok responses.

func (*Client) PollOnce

func (c *Client) PollOnce(ctx context.Context, deviceCode string) (*DeviceTokenResponse, error)

PollOnce does one POST /v1/auth/device/token call and returns the parsed response, mapping the documented error codes to typed errors. Callers drive the loop themselves so they can show progress.

func (*Client) PollUntilApproved

func (c *Client) PollUntilApproved(
	ctx context.Context,
	deviceCode string,
	interval time.Duration,
	maxInterval time.Duration,
	progress func(),
) (*DeviceTokenResponse, error)

PollUntilApproved repeatedly calls PollOnce honouring the slow_down / pending semantics. progress is invoked on each tick so the CLI can update the spinner. Returns the token response on approval, or a terminal error.

Defence against a compromised / hostile backend that returns slow_down indefinitely to keep the login hanging: cap consecutive slow_down responses, then bail with ErrSlowDown so the user gets a clear error instead of a forever-pinwheel. The context deadline is the outer bound; this is the inner one so a hostile server can't soak the full 10-minute device-code TTL waiting for the user to give up.

func (*Client) RequestDeviceCode

func (c *Client) RequestDeviceCode(ctx context.Context, clientName string) (*DeviceCodeResponse, error)

RequestDeviceCode kicks off the device flow.

type DeviceCodeRequest

type DeviceCodeRequest struct {
	ClientName string `json:"clientName,omitempty"`
}

DeviceCodeRequest is the body for POST /v1/auth/device/code.

type DeviceCodeResponse

type DeviceCodeResponse struct {
	DeviceCode              string `json:"deviceCode"`
	UserCode                string `json:"userCode"`
	VerificationURL         string `json:"verificationUrl"`
	VerificationURLComplete string `json:"verificationUrlComplete"`
	ExpiresIn               int    `json:"expiresIn"` // seconds
	Interval                int    `json:"interval"`  // seconds between polls
}

DeviceCodeResponse is the data block returned by POST /v1/auth/device/code.

type DeviceTokenResponse

type DeviceTokenResponse struct {
	Token     string `json:"token"`
	TokenID   string `json:"tokenId"`
	UserEmail string `json:"userEmail"`
}

DeviceTokenResponse is the data block returned by POST /v1/auth/device/token once the user has approved.