stromboli

func (*Client) CancelJob ¶

func (c *Client) CancelJob(ctx context.Context, jobID string) error

CancelJob cancels a pending or running job.

Use this method to stop a job that is no longer needed. Only pending and running jobs can be cancelled. Completed, failed, or already cancelled jobs cannot be cancelled (returns 409 Conflict error).

Example:

err := client.CancelJob(ctx, "job-abc123")
if err != nil {
    if errors.Is(err, stromboli.ErrNotFound) {
        fmt.Println("Job not found")
    } else {
        log.Fatal(err)
    }
}
fmt.Println("Job cancelled successfully")

Cancel a job immediately after starting:

job, _ := client.RunAsync(ctx, req)

// Changed our mind, cancel it
err := client.CancelJob(ctx, job.JobID)
if err != nil {
    log.Fatal(err)
}

func (*Client) ClaudeStatus ¶

func (c *Client) ClaudeStatus(ctx context.Context) (*ClaudeStatus, error)

ClaudeStatus returns the Claude configuration status.

Use this method to check if the Stromboli server has valid Claude credentials configured. If not configured, execution requests will fail.

Example:

status, err := client.ClaudeStatus(ctx)
if err != nil {
    log.Fatalf("Failed to check Claude status: %v", err)
}

if !status.Configured {
    log.Fatalf("Claude is not configured: %s", status.Message)
}

fmt.Println("Claude is ready for execution")

The context can be used to set a timeout or cancel the request:

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
status, err := client.ClaudeStatus(ctx)

func (*Client) ClearToken ¶

func (c *Client) ClearToken()

ClearToken removes the Bearer token from the client.

This is equivalent to calling SetToken("") but more explicit. Use this after Client.Logout to clear local state.

Example:

client.Logout(ctx)
client.ClearToken()

func (*Client) CreateSecret ¶

func (c *Client) CreateSecret(ctx context.Context, req *CreateSecretRequest) error

CreateSecret creates a new Podman secret.

Secrets can be used to securely pass sensitive data (API keys, tokens, etc.) to containers without exposing them in environment variables or command lines.

Example:

err := client.CreateSecret(ctx, &stromboli.CreateSecretRequest{
    Name:  "github-token",
    Value: "ghp_xxxx...",
})
if err != nil {
    log.Fatal(err)
}

Returns ErrSecretExists if a secret with this name already exists:

err := client.CreateSecret(ctx, req)
if errors.Is(err, stromboli.ErrSecretExists) {
    fmt.Println("Secret already exists")
}

func (*Client) DeleteSecret ¶

func (c *Client) DeleteSecret(ctx context.Context, name string) error

DeleteSecret permanently deletes a Podman secret.

WARNING: This action cannot be undone. Secrets currently in use by running containers may cause those containers to fail.

Example:

err := client.DeleteSecret(ctx, "github-token")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Secret deleted")

Returns ErrNotFound if the secret doesn't exist:

err := client.DeleteSecret(ctx, "unknown-secret")
if errors.Is(err, stromboli.ErrNotFound) {
    fmt.Println("Secret not found")
}

func (*Client) DestroySession ¶

func (c *Client) DestroySession(ctx context.Context, sessionID string) error

DestroySession removes a session and all its stored data.

Use this method to clean up old sessions that are no longer needed. This operation is permanent and cannot be undone.

Example:

err := client.DestroySession(ctx, "sess-abc123")
if err != nil {
    if errors.Is(err, stromboli.ErrNotFound) {
        fmt.Println("Session not found")
    } else {
        log.Fatal(err)
    }
}
fmt.Println("Session destroyed")

Bulk cleanup:

sessions, _ := client.ListSessions(ctx)
for _, id := range sessions {
    if err := client.DestroySession(ctx, id); err != nil {
        log.Printf("Failed to destroy %s: %v\n", id, err)
    }
}

func (*Client) GetImage ¶

func (c *Client) GetImage(ctx context.Context, name string) (*Image, error)

GetImage returns detailed information about a specific container image.

This includes all labels, compatibility information, and available tools.

Example:

image, err := client.GetImage(ctx, "python:3.12-slim")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Image: %s\n", image.ID)
fmt.Printf("Compatible: %v\n", image.Compatible)
fmt.Printf("Tools: %v\n", image.Tools)

Returns ErrImageNotFound if the image doesn't exist locally:

image, err := client.GetImage(ctx, "nonexistent:latest")
if errors.Is(err, stromboli.ErrImageNotFound) {
    fmt.Println("Image not found")
}

func (*Client) GetJob ¶

func (c *Client) GetJob(ctx context.Context, jobID string) (*Job, error)

GetJob returns the status and result of an async job.

Use this method to poll for job completion or check the status of a previously started async execution.

Basic polling example:

job, _ := client.RunAsync(ctx, req)

for {
    status, err := client.GetJob(ctx, job.JobID)
    if err != nil {
        log.Fatal(err)
    }

    switch {
    case status.IsCompleted():
        fmt.Println(status.Output)
        return
    case status.IsFailed():
        log.Fatalf("Job failed: %s", status.Error)
    case status.IsRunning():
        fmt.Println("Still running...")
        time.Sleep(2 * time.Second)
    }
}

Returns ErrNotFound if the job doesn't exist:

status, err := client.GetJob(ctx, "invalid-id")
if errors.Is(err, stromboli.ErrNotFound) {
    fmt.Println("Job not found")
}

func (*Client) GetMessage ¶

func (c *Client) GetMessage(ctx context.Context, sessionID, messageID string) (*Message, error)

GetMessage returns a specific message from session history by UUID.

Use this method to retrieve full details about a specific message, including its content, tool calls, and results.

Example:

msg, err := client.GetMessage(ctx, "sess-abc123", "msg-uuid-456")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Role: %s\n", msg.Type)
fmt.Printf("Content: %v\n", msg.Content)

func (*Client) GetMessages ¶

func (c *Client) GetMessages(ctx context.Context, sessionID string, opts *GetMessagesOptions) (*MessagesResponse, error)

GetMessages returns paginated conversation history for a session.

Use this method to retrieve past messages from a session, including user prompts, assistant responses, tool calls, and results.

Basic usage:

messages, err := client.GetMessages(ctx, "sess-abc123", nil)
if err != nil {
    log.Fatal(err)
}

for _, msg := range messages.Messages {
    fmt.Printf("[%s] %s\n", msg.Type, msg.UUID)
}

With pagination:

messages, _ := client.GetMessages(ctx, "sess-abc123", &stromboli.GetMessagesOptions{
    Limit:  50,
    Offset: 100,
})

if messages.HasMore {
    // Fetch next page
    nextPage, _ := client.GetMessages(ctx, "sess-abc123", &stromboli.GetMessagesOptions{
        Limit:  50,
        Offset: messages.Offset + messages.Limit,
    })
}

func (*Client) GetSecret ¶

func (c *Client) GetSecret(ctx context.Context, name string) (*Secret, error)

GetSecret retrieves metadata for a specific secret.

For security, the actual secret value is never returned - only the ID, name, and creation time.

Example:

secret, err := client.GetSecret(ctx, "github-token")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Secret %s created at %s\n", secret.Name, secret.CreatedAt)

Returns ErrNotFound if the secret doesn't exist:

secret, err := client.GetSecret(ctx, "unknown-secret")
if errors.Is(err, stromboli.ErrNotFound) {
    fmt.Println("Secret not found")
}

func (*Client) GetToken ¶

func (c *Client) GetToken(ctx context.Context, clientID string) (*TokenResponse, error)

GetToken obtains JWT tokens using a client ID.

Use this method to authenticate with the Stromboli API. The returned tokens can be used for subsequent authenticated requests.

Example:

tokens, err := client.GetToken(ctx, "my-client-id")
if err != nil {
    log.Fatal(err)
}

// Set the token for future requests
client.SetToken(tokens.AccessToken)

// Token expires in tokens.ExpiresIn seconds
fmt.Printf("Token expires in %d seconds\n", tokens.ExpiresIn)

func (*Client) Health ¶

func (c *Client) Health(ctx context.Context) (*HealthResponse, error)

Health returns the health status of the Stromboli API.

Use this method to:

• Check if the API is reachable and healthy
• Verify the server version
• Check the status of individual components (e.g., Podman)

Example:

health, err := client.Health(ctx)
if err != nil {
    log.Fatalf("API is unreachable: %v", err)
}

if !health.IsHealthy() {
    for _, c := range health.Components {
        if !c.IsHealthy() {
            log.Printf("Component %s is unhealthy: %s", c.Name, c.Error)
        }
    }
}

fmt.Printf("API v%s is healthy\n", health.Version)

The context can be used to set a timeout or cancel the request:

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
health, err := client.Health(ctx)

func (*Client) ListImages ¶

func (c *Client) ListImages(ctx context.Context) ([]*Image, error)

ListImages returns all local container images sorted by compatibility rank.

Images are ranked by their compatibility with Stromboli:

• Rank 1-2: Verified compatible (have required tools)
• Rank 3: Standard glibc (compatible)
• Rank 4: Incompatible (Alpine/musl)

Example:

images, err := client.ListImages(ctx)
if err != nil {
    log.Fatal(err)
}

for _, img := range images {
    fmt.Printf("%s:%s (rank %d, compatible: %v)\n",
        img.Repository, img.Tag, img.CompatibilityRank, img.Compatible)
}

func (*Client) ListJobs ¶

func (c *Client) ListJobs(ctx context.Context) ([]*Job, error)

ListJobs returns all async jobs.

Use this method to get an overview of all jobs, their status, and when they were created. The list includes pending, running, completed, failed, and cancelled jobs.

Example:

jobs, err := client.ListJobs(ctx)
if err != nil {
    log.Fatal(err)
}

for _, job := range jobs {
    fmt.Printf("%s: %s (created: %s)\n", job.ID, job.Status, job.CreatedAt)
}

Filter by status:

jobs, _ := client.ListJobs(ctx)
for _, job := range jobs {
    if job.IsRunning() {
        fmt.Printf("Job %s is still running\n", job.ID)
    }
}

func (*Client) ListSecrets ¶

func (c *Client) ListSecrets(ctx context.Context) ([]*Secret, error)

ListSecrets returns all available Podman secrets.

These secrets can be injected into container execution environments using [PodmanOptions.SecretsEnv].

Example:

secrets, err := client.ListSecrets(ctx)
if err != nil {
    log.Fatal(err)
}

for _, s := range secrets {
    fmt.Printf("Secret: %s (created: %s)\n", s.Name, s.CreatedAt)
}

Using secrets in execution:

secrets, _ := client.ListSecrets(ctx)

result, _ := client.Run(ctx, &stromboli.RunRequest{
    Prompt: "Use my GitHub token to list repos",
    Podman: &stromboli.PodmanOptions{
        SecretsEnv: map[string]string{
            "GITHUB_TOKEN": secrets[0].Name, // Use first available secret
        },
    },
})

func (*Client) ListSessions ¶

func (c *Client) ListSessions(ctx context.Context) ([]string, error)

ListSessions returns all existing session IDs.

Sessions are created automatically when running Claude with a new conversation. Use this method to list all available sessions for resumption or cleanup.

Example:

sessionIDs, err := client.ListSessions(ctx)
if err != nil {
    log.Fatal(err)
}

for _, id := range sessionIDs {
    fmt.Printf("Session: %s\n", id)
}

To continue a specific session, use the session ID with [ClaudeOptions.SessionID]:

result, _ := client.Run(ctx, &stromboli.RunRequest{
    Prompt: "What did we discuss earlier?",
    Claude: &stromboli.ClaudeOptions{
        SessionID: sessionIDs[0],
        Resume:    true,
    },
})

func (*Client) Logout ¶

func (c *Client) Logout(ctx context.Context) (*LogoutResponse, error)

Logout invalidates the current access token.

After calling this method, the token will no longer be accepted by the API. This method requires a valid token to be set using Client.SetToken.

Example:

client.SetToken(accessToken)

result, err := client.Logout(ctx)
if err != nil {
    log.Fatal(err)
}

if result.Success {
    fmt.Println("Successfully logged out")
    client.SetToken("") // Clear the token
}

func (*Client) PullImage ¶

func (c *Client) PullImage(ctx context.Context, req *PullImageRequest) (*PullImageResponse, error)

PullImage pulls a container image from a registry.

This operation may take some time for large images.

Example:

result, err := client.PullImage(ctx, &stromboli.PullImageRequest{
    Image:    "python:3.12-slim",
    Platform: "linux/amd64",
})
if err != nil {
    log.Fatal(err)
}

if result.Success {
    fmt.Printf("Pulled image %s (ID: %s)\n", result.Image, result.ImageID)
}

func (*Client) RefreshToken ¶

func (c *Client) RefreshToken(ctx context.Context, refreshToken string) (*TokenResponse, error)

RefreshToken obtains a new access token using a refresh token.

Use this method when your access token has expired. The refresh token has a longer lifetime and can be used to obtain new access tokens.

Example:

// When access token expires, use refresh token
newTokens, err := client.RefreshToken(ctx, tokens.RefreshToken)
if err != nil {
    // Refresh token may also be expired, need to re-authenticate
    log.Fatal(err)
}

client.SetToken(newTokens.AccessToken)

func (*Client) Run ¶

func (c *Client) Run(ctx context.Context, req *RunRequest) (*RunResponse, error)

Run executes Claude synchronously and waits for the result.

This method blocks until Claude completes execution or an error occurs. For long-running tasks, consider using Client.RunAsync instead.

Basic usage:

result, err := client.Run(ctx, &stromboli.RunRequest{
    Prompt: "Hello, Claude!",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Output)

With configuration:

result, err := client.Run(ctx, &stromboli.RunRequest{
    Prompt:  "Review this code for security issues",
    Workdir: "/workspace",
    Claude: &stromboli.ClaudeOptions{
        Model:        stromboli.ModelSonnet,
        MaxBudgetUSD: 5.0,
        AllowedTools: []string{"Read", "Glob", "Grep"},
    },
    Podman: &stromboli.PodmanOptions{
        Memory:  "2g",
        Timeout: "10m",
        Volumes: []string{"/home/user/project:/workspace:ro"},
    },
})

Continuing a conversation:

// First request
result1, _ := client.Run(ctx, &stromboli.RunRequest{
    Prompt: "Remember: my favorite color is blue",
})

// Continue the conversation
result2, _ := client.Run(ctx, &stromboli.RunRequest{
    Prompt: "What's my favorite color?",
    Claude: &stromboli.ClaudeOptions{
        SessionID: result1.SessionID,
        Resume:    true,
    },
})

Timeout Behavior ¶

The effective request timeout is determined by the shorter of:

• The client's configured timeout (via WithTimeout)
• The context's deadline (if set via context.WithTimeout)

For long-running tasks, either increase the client timeout or use Client.RunAsync instead.

The context can be used for cancellation:

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()
result, err := client.Run(ctx, req)

func (*Client) RunAsync ¶

func (c *Client) RunAsync(ctx context.Context, req *RunRequest) (*AsyncRunResponse, error)

RunAsync starts Claude execution asynchronously and returns a job ID.

Use this method for long-running tasks. Poll the job status with Client.GetJob or configure a webhook to be notified on completion.

Basic usage:

job, err := client.RunAsync(ctx, &stromboli.RunRequest{
    Prompt: "Analyze this large codebase",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Job started: %s\n", job.JobID)

With webhook notification:

job, err := client.RunAsync(ctx, &stromboli.RunRequest{
    Prompt:     "Review all files in the project",
    WebhookURL: "https://example.com/webhook",
})

Polling for completion:

job, _ := client.RunAsync(ctx, req)

for {
    status, err := client.GetJob(ctx, job.JobID)
    if err != nil {
        log.Fatal(err)
    }

    switch status.Status {
    case "completed":
        fmt.Println(status.Output)
        return
    case "failed":
        log.Fatalf("Job failed: %s", status.Error)
    case "running":
        fmt.Println("Still running...")
        time.Sleep(2 * time.Second)
    }
}

func (*Client) SearchImages ¶

func (c *Client) SearchImages(ctx context.Context, opts *SearchImagesOptions) ([]*ImageSearchResult, error)

SearchImages searches container registries for images matching the query.

Returns results from Docker Hub and other configured registries.

Example:

results, err := client.SearchImages(ctx, &stromboli.SearchImagesOptions{
    Query: "python",
    Limit: 10,
})
if err != nil {
    log.Fatal(err)
}

for _, r := range results {
    fmt.Printf("%s: %s (stars: %d, official: %v)\n",
        r.Name, r.Description, r.Stars, r.Official)
}

func (*Client) SetToken ¶

func (c *Client) SetToken(token string)

SetToken sets the Bearer token for authenticated requests.

This token is used for endpoints that require authentication, such as Client.ValidateToken and Client.Logout. SetToken is safe for concurrent use.

Token Validation ¶

Tokens are validated to prevent HTTP header injection attacks. If a token contains control characters (CR, LF, or other characters < 0x20), the token is rejected and a warning is logged. The previous token remains unchanged. This is a security measure - valid JWT tokens never contain these characters.

To check if a token was accepted, call [Client.getToken] after setting, or use Client.ValidateToken to verify with the server.

Empty Token ¶

Passing an empty string clears the token. Use Client.ClearToken for a more explicit way to remove the token.

Example:

tokens, _ := client.GetToken(ctx, "my-client-id")
client.SetToken(tokens.AccessToken)

// Now authenticated endpoints will work
validation, _ := client.ValidateToken(ctx)

func (*Client) Stream ¶

func (c *Client) Stream(ctx context.Context, req *StreamRequest) (*Stream, error)

Stream executes Claude and streams output in real-time.

This method connects to the SSE (Server-Sent Events) endpoint and returns a Stream that yields events as they arrive.

Timeout Behavior ¶

WARNING: The client timeout (WithTimeout) does NOT apply to streaming requests. If no context deadline is set and the server stops responding, this method may block indefinitely. Always use context.WithTimeout:

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()
stream, err := client.Stream(ctx, req)

The timeout behavior differs from regular requests because streams are designed for long-running connections where data arrives incrementally.

Basic Usage ¶

stream, err := client.Stream(ctx, &stromboli.StreamRequest{
    Prompt: "Write a haiku about Go programming",
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for stream.Next() {
    fmt.Print(stream.Event().Data)
}

if err := stream.Err(); err != nil {
    log.Fatal(err)
}

Channel Iteration ¶

stream, _ := client.Stream(ctx, req)
defer stream.Close()

for event := range stream.Events() {
    fmt.Print(event.Data)
}

Continuing a Conversation ¶

// First interaction
stream1, _ := client.Stream(ctx, &stromboli.StreamRequest{
    Prompt: "My name is Alice",
})
// ... consume stream1 ...
sessionID := "..." // Get from previous response

// Continue conversation
stream2, _ := client.Stream(ctx, &stromboli.StreamRequest{
    Prompt:    "What's my name?",
    SessionID: sessionID,
})

func (*Client) ValidateToken ¶

func (c *Client) ValidateToken(ctx context.Context) (*TokenValidation, error)

ValidateToken validates the current access token and returns its claims.

This method requires a valid token to be set using Client.SetToken.

Example:

client.SetToken(accessToken)

validation, err := client.ValidateToken(ctx)
if err != nil {
    log.Fatal(err)
}

if validation.Valid {
    fmt.Printf("Token valid for subject: %s\n", validation.Subject)
    fmt.Printf("Expires at: %d\n", validation.ExpiresAt)
}

func (*CompatibilityResult) IsCompatible ¶

func (r *CompatibilityResult) IsCompatible() bool

IsCompatible returns true if the status indicates compatibility.

func (CompatibilityStatus) String ¶

func (s CompatibilityStatus) String() string

String returns a human-readable representation of the status.

func (*ComponentHealth) IsHealthy ¶

func (c *ComponentHealth) IsHealthy() bool

IsHealthy returns true if the component status is "ok".

func (*Error) Error ¶

func (e *Error) Error() string

Error returns a string representation of the error.

The format is "stromboli: CODE: message" or "stromboli: CODE: message: cause" if there is an underlying error.

func (*Error) Is ¶

func (e *Error) Is(target error) bool

Is reports whether the target error matches this error.

Two errors match if they have the same Code. The Status field is NOT compared, so errors.Is(err, ErrNotFound) matches any NOT_FOUND error regardless of the HTTP status code. This allows sentinel errors to match all instances of that error type.

Example:

if errors.Is(err, stromboli.ErrNotFound) {
    // Handles any NOT_FOUND error (404, or otherwise)
}

func (*Error) Unwrap ¶

func (e *Error) Unwrap() error

Unwrap returns the underlying error cause.

This allows using errors.Is and errors.As to inspect the error chain.

func (*HealthResponse) IsHealthy ¶

func (h *HealthResponse) IsHealthy() bool

IsHealthy returns true if the overall status is "ok".

Example:

health, _ := client.Health(ctx)
if !health.IsHealthy() {
    log.Println("API is unhealthy!")
}

func (*Image) CreatedTime ¶

func (i *Image) CreatedTime() time.Time

CreatedTime parses Created as time.Time. Returns zero time if Created is empty or parsing fails.

NOTE: Parsing errors are silently ignored. If you need to validate the timestamp format, use time.Parse(time.RFC3339, i.Created) directly.

func (*Job) CreatedAtTime ¶

func (j *Job) CreatedAtTime() time.Time

CreatedAtTime parses CreatedAt as time.Time. Returns zero time if CreatedAt is empty or parsing fails.

NOTE: Parsing errors are silently ignored. If you need to validate the timestamp format, use time.Parse(time.RFC3339, j.CreatedAt) directly.

func (*Job) IsCancelled ¶

func (j *Job) IsCancelled() bool

IsCancelled returns true if the job was cancelled.

func (*Job) IsCompleted ¶

func (j *Job) IsCompleted() bool

IsCompleted returns true if the job completed successfully.

func (*Job) IsFailed ¶

func (j *Job) IsFailed() bool

IsFailed returns true if the job failed.

func (*Job) IsPending ¶

func (j *Job) IsPending() bool

IsPending returns true if the job is pending (queued but not yet started).

func (*Job) IsRunning ¶

func (j *Job) IsRunning() bool

IsRunning returns true if the job is still running.

func (*Job) UpdatedAtTime ¶

func (j *Job) UpdatedAtTime() time.Time

UpdatedAtTime parses UpdatedAt as time.Time. Returns zero time if UpdatedAt is empty or parsing fails.

NOTE: Parsing errors are silently ignored. If you need to validate the timestamp format, use time.Parse(time.RFC3339, j.UpdatedAt) directly.

func (*Message) ContentAsBlocks ¶

func (m *Message) ContentAsBlocks() (blocks []map[string]interface{}, skipped int, ok bool)

ContentAsBlocks returns the content as a slice of maps if it contains content blocks. Returns nil and false if content is not in block format.

WARNING: Non-map entries in the content array are skipped. The returned int indicates how many entries were skipped, allowing callers to detect data loss. If skipped > 0, some content was not map-typed and was omitted from results.

The ok return value indicates whether Content was in array format ([]interface{}), NOT whether any blocks were found. An empty content array returns ok=true with an empty blocks slice. Use ok=false to detect non-array content formats.

For more precise typing, use json.Marshal/Unmarshal:

data, _ := json.Marshal(msg.Content)
var blocks []YourBlockType
json.Unmarshal(data, &blocks)

func (*Message) ContentAsString ¶

func (m *Message) ContentAsString() (string, bool)

ContentAsString returns the content as a string if it is a simple string message. Returns empty string and false if content is not a string.

Example:

if text, ok := msg.ContentAsString(); ok {
    fmt.Println(text)
}

func (*Message) TimestampTime ¶

func (m *Message) TimestampTime() time.Time

TimestampTime parses Timestamp as time.Time. Returns zero time if Timestamp is empty or parsing fails.

NOTE: Parsing errors are silently ignored. If you need to validate the timestamp format, use time.Parse(time.RFC3339, m.Timestamp) directly.

func (Model) String ¶

func (m Model) String() string

String returns the string representation of the Model.

func (*RunResponse) IsSuccess ¶

func (r *RunResponse) IsSuccess() bool

IsSuccess returns true if the execution completed successfully.

func (*Secret) CreatedAtTime ¶

func (s *Secret) CreatedAtTime() time.Time

CreatedAtTime parses CreatedAt as time.Time. Returns zero time if CreatedAt is empty or parsing fails.

NOTE: Parsing errors are silently ignored. If you need to validate the timestamp format, use time.Parse(time.RFC3339, s.CreatedAt) directly.

func (*Stream) Close ¶

func (s *Stream) Close() error

Close closes the stream and releases resources.

Always call Close when done with the stream, preferably with defer. This is required even if Stream.Next returns false due to an error, as the underlying HTTP response body must be closed to release resources.

Close is safe to call multiple times and is thread-safe.

Example:

stream, err := client.Stream(ctx, req)
if err != nil {
    log.Fatal(err)
}
defer stream.Close() // Always close, even on errors

func (*Stream) Err ¶

func (s *Stream) Err() error

Err returns any error that occurred during streaming.

Returns nil if:

• The stream completed successfully (normal EOF)
• The stream is still active
• No error has occurred yet

To distinguish between "completed successfully" and "still active", check if Stream.Next returned false. After Next returns false, Err() == nil means normal completion; Err() != nil means an error.

func (*Stream) Event ¶

func (s *Stream) Event() *StreamEvent

Event returns the current event.

Call this after Stream.Next returns true. If called before the first successful Stream.Next call, returns an empty event (not nil) to prevent nil pointer dereferences.

This method is thread-safe and can be called concurrently with Stream.Next.

func (*Stream) EventsWithContext ¶

func (s *Stream) EventsWithContext(ctx context.Context) <-chan *StreamEvent

EventsWithContext returns a channel that yields events from the stream.

The channel is closed when the stream ends, an error occurs, or the context is cancelled. This is the preferred method to avoid goroutine leaks if you stop reading before the stream ends.

Example:

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()

for event := range stream.EventsWithContext(ctx) {
    fmt.Print(event.Data)
}
if err := stream.Err(); err != nil {
    log.Fatal(err)
}

func (*Stream) Next ¶

func (s *Stream) Next() bool

Next advances to the next event in the stream.

Returns true if an event is available, false if the stream is exhausted or an error occurred. Call Stream.Err to check for errors.

Example:

for stream.Next() {
    event := stream.Event()
    fmt.Print(event.Data)
}