client

Documentation

Index

• Constants
• Variables
• func IsBadRequest(err error) bool
• func IsNotFound(err error) bool
• type AuthenticationType
• type Client
  • func NewClient(opts ...Option) (Client, error)
• type OIDCTokenExchangeConfig
• type Option
  • func WithAuthBasic(username, password string) Option
  • func WithAuthCustom() Option
  • func WithAuthNone() Option
  • func WithAuthOIDC(clientID, clientSecret, tokenURL string, scopes ...string) Option
  • func WithAuthOIDCInsecure(clientID, clientSecret, tokenURL string, allowInsecure bool, scopes ...string) Option
  • func WithAuthOIDCTokenExchange(cfg OIDCTokenExchangeConfig) Option
  • func WithAuthPersonalToken(token string) Option
  • func WithBaseURL(url string) Option
  • func WithCircuitBreaker(name string, st gobreaker.Settings) Option
  • func WithInsecure() Option
  • func WithMiddleware(mw func(*resty.Client, *resty.Request) error) Option
  • func WithOrganisation(organisationIdentity string) Option
  • func WithProject(projectIdentity string) Option
  • func WithRateLimit(rps float64, burst int) Option
  • func WithRetries(count int, waitTime, maxWaitTime time.Duration) Option
  • func WithTimeout(d time.Duration) Option
  • func WithToken(token string) Option
  • func WithUserAgent(ua string) Option
• type ServerErrorMessage

Constants

const (
	GET    httpMethod = "GET"
	POST   httpMethod = "POST"
	PUT    httpMethod = "PUT"
	PATCH  httpMethod = "PATCH"
	DELETE httpMethod = "DELETE"
)

const (
	DefaultUserAgent = "thalassa-cloud-client-go (https://github.com/thalassa-cloud/client-go)"
)

Variables

var (
	ErrMissingBaseURL          = errors.New("missing base URL; use WithBaseURL(...)")
	ErrMissingOIDCConfig       = errors.New("OIDC configuration is missing")
	ErrEmptyPersonalToken      = errors.New("personal access token cannot be empty")
	ErrMissingToken            = errors.New("token cannot be empty")
	ErrMissingBasicCredentials = errors.New("basic auth requires username/password")
	ErrOIDCTokenExchangeConfig = errors.New("OIDC token exchange requires token URL, organisation ID, service account ID, and either SubjectToken or SubjectTokenFile")
	ErrUnsupportedHTTPMethod   = errors.New("unsupported HTTP method")
	ErrNotFound                = errors.New("not found")
	ErrBadRequest              = errors.New("bad request")
)

Functions

func IsBadRequest

func IsBadRequest(err error) bool

func IsNotFound

func IsNotFound(err error) bool

Types

type AuthenticationType

type AuthenticationType int

const (
	AuthNone AuthenticationType = iota
	AuthOIDC
	AuthToken
	AuthPersonalAccessToken
	AuthBasic
	AuthCustom
	AuthOIDCTokenExchange
)

type Client

type Client interface {
	Do(ctx context.Context, req *resty.Request, method httpMethod, url string) (*resty.Response, error)
	Check(resp *resty.Response) error

	R() *resty.Request

	WithOptions(opts ...Option) Client

	// GetOrganisationIdentity returns the organisation identity for the client, if set
	GetOrganisationIdentity() string

	// SetOrganisation sets the organisation for the client
	SetOrganisation(organisation string)

	// GetAuthToken returns the authentication token for the client, if set
	GetAuthToken() string

	// GetBaseURL returns the base URL for the client
	GetBaseURL() string

	// DialWebsocket creates a websocket connection to the specified URL
	DialWebsocket(ctx context.Context, wsURL string) (*websocket.Conn, error)

	// RawRequest performs an HTTP request using the client's base URL, authentication,
	// and configuration (rate limiting, organisation/project headers, etc.).
	// method is the HTTP method (GET, POST, PUT, PATCH, DELETE). path is the request path
	// relative to the base URL (e.g. "/v1/resources"). body is optional; when non-nil,
	// it is sent as the request body with Content-Type: application/json.
	// Returns the resty response so callers can read status code, headers, and body.
	RawRequest(ctx context.Context, method, path string, body []byte) (*resty.Response, error)
}

func NewClient

func NewClient(opts ...Option) (Client, error)

NewClient applies all options, configures authentication, and returns the client.

type OIDCTokenExchangeConfig

type OIDCTokenExchangeConfig struct {
	TokenURL         string
	SubjectToken     string
	SubjectTokenFile string
	OrganisationID   string
	ServiceAccountID string
	// AccessTokenLifetime is optional (e.g. "39600s"); sent as access_token_lifetime when non-empty.
	AccessTokenLifetime string
}

OIDCTokenExchangeConfig configures exchanging an external OIDC JWT (e.g. GitLab ID token) for a Thalassa Cloud API bearer token via POST application/x-www-form-urlencoded to TokenURL (typically {api}/oidc/token).

type Option

type Option func(*thalassaCloudClient) error

Option is a function that modifies the Client.

func WithAuthBasic

func WithAuthBasic(username, password string) Option

func WithAuthCustom

func WithAuthCustom() Option

func WithAuthNone

func WithAuthNone() Option

func WithAuthOIDC

func WithAuthOIDC(clientID, clientSecret, tokenURL string, scopes ...string) Option

WithAuthOIDC uses client credentials for service-to-service flows.

func WithAuthOIDCInsecure

func WithAuthOIDCInsecure(clientID, clientSecret, tokenURL string, allowInsecure bool, scopes ...string) Option

func WithAuthOIDCTokenExchange

func WithAuthOIDCTokenExchange(cfg OIDCTokenExchangeConfig) Option

WithAuthOIDCTokenExchange exchanges a subject JWT for an API access token before each request when the cached token is missing or expired. The resulting bearer token is used like AuthOIDC.

Provide the subject JWT via SubjectToken, or SubjectTokenFile (contents read at each exchange; use for mounted tokens in Kubernetes so rotation is picked up on refresh).

func WithAuthPersonalToken

func WithAuthPersonalToken(token string) Option

func WithBaseURL

func WithBaseURL(url string) Option

func WithCircuitBreaker

func WithCircuitBreaker(name string, st gobreaker.Settings) Option

WithCircuitBreaker configures a circuit breaker using sony/gobreaker.

func WithInsecure

func WithInsecure() Option

WithInsecure disables SSL certificate verification. This should only be used for development/testing purposes.

func WithMiddleware

func WithMiddleware(mw func(*resty.Client, *resty.Request) error) Option

func WithOrganisation

func WithOrganisation(organisationIdentity string) Option

func WithProject

func WithProject(projectIdentity string) Option

func WithRateLimit

func WithRateLimit(rps float64, burst int) Option

func WithRetries

func WithRetries(count int, waitTime, maxWaitTime time.Duration) Option

func WithTimeout

func WithTimeout(d time.Duration) Option

func WithToken

func WithToken(token string) Option

func WithUserAgent

func WithUserAgent(ua string) Option

type ServerErrorMessage

type ServerErrorMessage struct {
	Message string `json:"message"`
}