api

package
v0.2.11 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default Tusk Cloud API URL
	DefaultBaseURL = "https://api.usetusk.ai"

	TestRunServiceAPIPath    = "/api/drift/test_run_service"
	ClientServiceAPIPath     = "/api/drift/client_service"
	SpanExportServiceAPIPath = "/api/drift/tusk.drift.backend.v1.SpanExportService"
)
View Source 
const DocsSetupURL = "https://docs.usetusk.ai/onboarding"
View Source 
const DriftQueryAPIPath = "/api/drift/query"

Variables

View Source 
var (
	ErrFetchTraceTests          = errors.New("unable to fetch tests from Tusk Cloud")
	ErrFetchTraceTestIDs        = errors.New("unable to fetch test IDs from Tusk Cloud and no cache available")
	ErrFetchNewTraceTests       = errors.New("unable to fetch new tests from Tusk Cloud")
	ErrFetchPreAppStartSpanIDs  = errors.New("unable to fetch pre-app-start span IDs from Tusk Cloud and no cache available")
	ErrFetchNewPreAppStartSpans = errors.New("unable to fetch new pre-app-start spans from Tusk Cloud")
	ErrFetchPreAppStartSpans    = errors.New("unable to fetch pre-app-start spans from Tusk Cloud")
	ErrFetchGlobalSpanIDs       = errors.New("unable to fetch global span IDs from Tusk Cloud and no cache available")
	ErrFetchNewGlobalSpans      = errors.New("unable to fetch new global spans from Tusk Cloud")
	ErrFetchGlobalSpans         = errors.New("unable to fetch global spans from Tusk Cloud")
)

Functions

func FetchAllGlobalSpans 

func FetchAllGlobalSpans(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
) ([]*core.Span, error)

FetchAllGlobalSpans fetches all global spans without caching (fallback).

func FetchAllPreAppStartSpans 

func FetchAllPreAppStartSpans(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
) ([]*core.Span, error)

FetchAllPreAppStartSpans fetches all pre-app-start spans without caching (fallback).

func FetchAllTraceTests 

func FetchAllTraceTests(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
	opts *FetchAllTraceTestsOptions,
) ([]*backend.TraceTest, error)

FetchAllTraceTests fetches all trace tests from the cloud with a progress bar. This is the shared implementation used by both `tusk list -c` and `tusk run -c`.

func FetchAllTraceTestsWithCache 

func FetchAllTraceTestsWithCache(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*backend.TraceTest, error)

FetchAllTraceTestsWithCache fetches trace tests using ID-based cache diffing. It only fetches new traces and removes deleted ones from cache. On network error, it falls back to cached data if available.

func FetchDriftRunTraceTests 

func FetchDriftRunTraceTests(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	driftRunID string,
	opts *FetchAllTraceTestsOptions,
) ([]*backend.TraceTest, error)

FetchDriftRunTraceTests fetches trace tests for a specific drift run with a progress bar.

func FetchGlobalSpansWithCache 

func FetchGlobalSpansWithCache(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchGlobalSpansWithCache fetches global spans using ID-based cache diffing. It only fetches new spans and removes deleted ones from cache. On network error, it falls back to cached data if available.

func FetchPreAppStartSpansWithCache 

func FetchPreAppStartSpansWithCache(
	ctx context.Context,
	client *TuskClient,
	auth AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchPreAppStartSpansWithCache fetches pre-app-start spans using ID-based cache diffing. It only fetches new spans and removes deleted ones from cache. On network error, it falls back to cached data if available.

func GetBaseURL 

func GetBaseURL() string

GetBaseURL returns the API base URL with the following priority: 1. TUSK_API_URL environment variable 2. tusk_api.url from .tusk/config.yaml 3. Default URL (https://api.usetusk.ai)

func IsSkippableError 

func IsSkippableError(err error) bool

IsSkippableError checks if an error is a SkippableError

func SetupCloud 

func SetupCloud(ctx context.Context, requireServiceID bool) (*TuskClient, AuthOptions, *config.Config, error)

func UserEmail 

func UserEmail(user *backend.UserAuthInfo) string

UserEmail extracts the best email/username from an AuthInfoUser. Prefers CodeHostingUsername (GitHub/GitLab handle) over email.

Types

type ApiError 

type ApiError struct {
	StatusCode int
	Message    string
	RawBody    string
}

ApiError represents a non-2xx HTTP response from the Tusk API. Consumers can use errors.As to extract the status code and message.

func (*ApiError) Error 

func (e *ApiError) Error() string

type AuthOptions 

type AuthOptions struct {
	APIKey       string
	BearerToken  string
	TuskClientID string
}

type Deviation 

type Deviation struct {
	Type        string `json:"type"`
	Field       string `json:"field"`
	Expected    any    `json:"expected"`
	Actual      any    `json:"actual"`
	Description string `json:"description"`
	Severity    string `json:"severity"`
}

type FetchAllTraceTestsOptions 

type FetchAllTraceTestsOptions struct {
	// Message to show in the progress bar
	Message string
	// PageSize for pagination (default 25)
	PageSize int32
	// StatusFilter filters by trace test suite status (e.g., DRAFT, IN_SUITE).
	// If nil, the server defaults to IN_SUITE.
	StatusFilter *backend.TraceTestStatus
}

FetchAllTraceTestsOptions configures the fetch behavior

type MockInteraction 

type MockInteraction struct {
	Service   string           `json:"service"`
	Request   RecordedRequest  `json:"request"`
	Response  RecordedResponse `json:"response"`
	Order     int              `json:"order"`
	Timestamp time.Time        `json:"timestamp"`
}

type RecordedRequest 

type RecordedRequest struct {
	Method  string              `json:"method"`
	Path    string              `json:"path"`
	Headers map[string][]string `json:"headers"`
	Body    any                 `json:"body,omitempty"`
	Query   map[string][]string `json:"query,omitempty"`
}

type RecordedResponse 

type RecordedResponse struct {
	Status  int                 `json:"status"`
	Headers map[string][]string `json:"headers"`
	Body    any                 `json:"body,omitempty"`
}

type RetryConfig 

type RetryConfig struct {
	MaxRetries  int
	BaseBackoff time.Duration
	MaxBackoff  time.Duration
	JitterMin   float64
	JitterMax   float64
}

func DefaultRetryConfig 

func DefaultRetryConfig(maxRetries int) RetryConfig

DefaultRetryConfig returns normal retry configuration

func FastRetryConfig 

func FastRetryConfig(maxRetries int) RetryConfig

FastRetryConfig returns retry configuration for testing

type SkippableError 

type SkippableError struct {
	Code    string
	Message string
}

SkippableError is returned for errors that should be treated as a no-op in CI mode (e.g. feature disabled after trial expiry, repo disabled, repo not found)

func (*SkippableError) Error 

func (e *SkippableError) Error() string

type TestRecording 

type TestRecording struct {
	ID        string            `json:"id"`
	ServiceID string            `json:"service_id"`
	TraceID   string            `json:"trace_id"`
	Method    string            `json:"method"`
	Path      string            `json:"path"`
	Request   RecordedRequest   `json:"request"`
	Response  RecordedResponse  `json:"response"`
	Mocks     []MockInteraction `json:"mocks"`
	Timestamp time.Time         `json:"timestamp"`
	Metadata  map[string]any    `json:"metadata"`
}

type TestResult 

type TestResult struct {
	TestID      string      `json:"test_id"`
	ServiceID   string      `json:"service_id"`
	Passed      bool        `json:"passed"`
	Duration    int         `json:"duration_ms"`
	Deviations  []Deviation `json:"deviations,omitempty"`
	Error       string      `json:"error,omitempty"`
	ExecutedAt  time.Time   `json:"executed_at"`
	Environment string      `json:"environment"`
}

type TuskClient 

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

func NewClient 

func NewClient(baseURL, apiKey string) *TuskClient

func (*TuskClient) AggregateDriftSpans added in v0.2.10 

func (c *TuskClient) AggregateDriftSpans(ctx context.Context, input *driftquery.AggregateSpansInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) CreateApiKey 

func (c *TuskClient) CreateApiKey(ctx context.Context, in *backend.CreateApiKeyRequest, auth AuthOptions) (*backend.CreateApiKeyResponse, error)

func (*TuskClient) CreateDriftRun 

func (c *TuskClient) CreateDriftRun(ctx context.Context, in *backend.CreateDriftRunRequest, auth AuthOptions) (string, error)

func (*TuskClient) CreateObservableService 

func (c *TuskClient) CreateObservableService(ctx context.Context, in *backend.CreateObservableServiceRequest, auth AuthOptions) (*backend.CreateObservableServiceResponse, error)

func (*TuskClient) ExportSpans 

func (c *TuskClient) ExportSpans(ctx context.Context, in *backend.ExportSpansRequest, auth AuthOptions) (*backend.ExportSpansResponse, error)

ExportSpans uploads spans to Tusk Cloud

func (*TuskClient) GetAllGlobalSpanIds 

func (c *TuskClient) GetAllGlobalSpanIds(ctx context.Context, in *backend.GetAllGlobalSpanIdsRequest, auth AuthOptions) (*backend.GetAllGlobalSpanIdsResponseSuccess, error)

GetAllGlobalSpanIds fetches all global span IDs for a service (lightweight, no pagination).

func (*TuskClient) GetAllPreAppStartSpanIds 

func (c *TuskClient) GetAllPreAppStartSpanIds(ctx context.Context, in *backend.GetAllPreAppStartSpanIdsRequest, auth AuthOptions) (*backend.GetAllPreAppStartSpanIdsResponseSuccess, error)

GetAllPreAppStartSpanIds fetches all pre-app-start span IDs for a service (lightweight, no pagination).

func (*TuskClient) GetAllTraceTestIds 

func (c *TuskClient) GetAllTraceTestIds(ctx context.Context, in *backend.GetAllTraceTestIdsRequest, auth AuthOptions) (*backend.GetAllTraceTestIdsResponseSuccess, error)

GetAllTraceTestIds fetches all trace test IDs for a service (lightweight, no pagination).

func (*TuskClient) GetAllTraceTests 

func (c *TuskClient) GetAllTraceTests(ctx context.Context, in *backend.GetAllTraceTestsRequest, auth AuthOptions) (*backend.GetAllTraceTestsResponseSuccess, error)

func (*TuskClient) GetAuthInfo 

func (c *TuskClient) GetAuthInfo(ctx context.Context, in *backend.GetAuthInfoRequest, auth AuthOptions) (*backend.GetAuthInfoResponse, error)

func (*TuskClient) GetDriftRunTraceTests 

func (c *TuskClient) GetDriftRunTraceTests(ctx context.Context, in *backend.GetDriftRunTraceTestsRequest, auth AuthOptions) (*backend.GetDriftRunTraceTestsResponseSuccess, error)

func (*TuskClient) GetDriftSchema added in v0.2.10 

func (c *TuskClient) GetDriftSchema(ctx context.Context, input *driftquery.GetSchemaInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) GetDriftSpansByIds added in v0.2.10 

func (c *TuskClient) GetDriftSpansByIds(ctx context.Context, input *driftquery.GetSpansByIdsInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) GetDriftTrace added in v0.2.10 

func (c *TuskClient) GetDriftTrace(ctx context.Context, input *driftquery.GetTraceInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) GetGlobalSpans 

func (c *TuskClient) GetGlobalSpans(ctx context.Context, in *backend.GetGlobalSpansRequest, auth AuthOptions) (*backend.GetGlobalSpansResponseSuccess, error)

func (*TuskClient) GetGlobalSpansByIds 

func (c *TuskClient) GetGlobalSpansByIds(ctx context.Context, in *backend.GetGlobalSpansByIdsRequest, auth AuthOptions) (*backend.GetGlobalSpansByIdsResponseSuccess, error)

GetGlobalSpansByIds fetches global spans by their IDs (batch fetch).

func (*TuskClient) GetLatestUnitTestRun 

func (c *TuskClient) GetLatestUnitTestRun(ctx context.Context, repo string, branch string, auth AuthOptions) (UnitTestRunSummary, error)

func (*TuskClient) GetObservableServiceInfo 

func (c *TuskClient) GetObservableServiceInfo(ctx context.Context, in *backend.GetObservableServiceInfoRequest, auth AuthOptions) (*backend.GetObservableServiceInfoResponseSuccess, error)

GetObservableServiceInfo fetches observable service info including default branch

func (*TuskClient) GetPreAppStartSpans 

func (c *TuskClient) GetPreAppStartSpans(ctx context.Context, in *backend.GetPreAppStartSpansRequest, auth AuthOptions) (*backend.GetPreAppStartSpansResponseSuccess, error)

func (*TuskClient) GetPreAppStartSpansByIds 

func (c *TuskClient) GetPreAppStartSpansByIds(ctx context.Context, in *backend.GetPreAppStartSpansByIdsRequest, auth AuthOptions) (*backend.GetPreAppStartSpansByIdsResponseSuccess, error)

GetPreAppStartSpansByIds fetches pre-app-start spans by their IDs (batch fetch).

func (*TuskClient) GetTraceTest 

func (c *TuskClient) GetTraceTest(ctx context.Context, in *backend.GetTraceTestRequest, auth AuthOptions) (*backend.GetTraceTestResponseSuccess, error)

func (*TuskClient) GetTraceTestsByIds 

func (c *TuskClient) GetTraceTestsByIds(ctx context.Context, in *backend.GetTraceTestsByIdsRequest, auth AuthOptions) (*backend.GetTraceTestsByIdsResponseSuccess, error)

GetTraceTestsByIds fetches trace tests by their IDs (batch fetch).

func (*TuskClient) GetUnitTestRun 

func (c *TuskClient) GetUnitTestRun(ctx context.Context, runID string, auth AuthOptions) (UnitTestRunDetails, error)

func (*TuskClient) GetUnitTestRunFiles 

func (c *TuskClient) GetUnitTestRunFiles(ctx context.Context, runID string, auth AuthOptions) (UnitTestRunFiles, error)

func (*TuskClient) GetUnitTestScenario 

func (c *TuskClient) GetUnitTestScenario(ctx context.Context, runID string, scenarioID string, auth AuthOptions) (UnitTestScenarioDetails, error)

func (*TuskClient) GetValidationTraceTests 

func (c *TuskClient) GetValidationTraceTests(ctx context.Context, in *backend.GetValidationTraceTestsRequest, auth AuthOptions) (*backend.GetValidationTraceTestsResponseSuccess, error)

GetValidationTraceTests fetches traces for validation (both DRAFT and IN_SUITE)

func (*TuskClient) ListDriftDistinctValues added in v0.2.10 

func (c *TuskClient) ListDriftDistinctValues(ctx context.Context, input *driftquery.ListDistinctValuesInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) ListDriftServices added in v0.2.10 

func (c *TuskClient) ListDriftServices(ctx context.Context, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) QueryDriftSpans added in v0.2.10 

func (c *TuskClient) QueryDriftSpans(ctx context.Context, input *driftquery.QuerySpansInput, auth AuthOptions) (json.RawMessage, error)

func (*TuskClient) RetryUnitTestRun added in v0.2.6 

func (c *TuskClient) RetryUnitTestRun(ctx context.Context, runID string, payload any, auth AuthOptions) (UnitTestRetryResult, error)

func (*TuskClient) SubmitUnitTestFeedback added in v0.2.6 

func (c *TuskClient) SubmitUnitTestFeedback(ctx context.Context, runID string, payload any, auth AuthOptions) (UnitTestFeedbackResult, error)

func (*TuskClient) UpdateDriftRunCIStatus 

func (c *TuskClient) UpdateDriftRunCIStatus(ctx context.Context, in *backend.UpdateDriftRunCIStatusRequest, auth AuthOptions) error

func (*TuskClient) UploadTraceTestResults 

func (c *TuskClient) UploadTraceTestResults(ctx context.Context, in *backend.UploadTraceTestResultsRequest, auth AuthOptions) error

func (*TuskClient) VerifyRepoAccess 

func (c *TuskClient) VerifyRepoAccess(ctx context.Context, in *backend.VerifyRepoAccessRequest, auth AuthOptions) (*backend.VerifyRepoAccessResponse, error)

type UnitTestFeedbackResult added in v0.2.6 

type UnitTestFeedbackResult map[string]any

type UnitTestRetryResult added in v0.2.6 

type UnitTestRetryResult map[string]any

type UnitTestRunDetails 

type UnitTestRunDetails map[string]any

type UnitTestRunFiles 

type UnitTestRunFiles map[string]any

type UnitTestRunSummary 

type UnitTestRunSummary map[string]any

type UnitTestScenarioDetails 

type UnitTestScenarioDetails map[string]any

Source Files

View all Source files

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.