rustbox

README

🦫 Rustbox Go SDK

Stdlib net/http only. Functional options. Synchronous API.

🚀 Install

go get github.com/orkait/rustbox-sdk/go

⚡ Quickstart

package main

import (
    "fmt"
    "os"
    rustbox "github.com/orkait/rustbox-sdk/go"
)

func main() {
    client := rustbox.New(os.Getenv("RUSTBOX_API_KEY"))
    result, err := client.Run(rustbox.SubmitRequest{
        Language: "python", Code: "print('hello')",
    })
    if err != nil { panic(err) }
    fmt.Println(result["verdict"], result["stdout"])  // AC hello
}

Run() submits, waits for sync completion, polls if needed, returns the verdict.

Profiles

// Judge profile (default) - short evaluation runs, no egress proxy.
client.Run(rustbox.SubmitRequest{Language: "python", Code: "print(1)"})

// Agent profile - longer jobs, egress proxy on, per-key byte budget.
// Requires a non-trial API key.
client.Run(rustbox.SubmitRequest{
    Language: "python", Code: "...", Profile: rustbox.ProfileAgent,
})

🔒 Errors

Sentinel errors. Use errors.Is to discriminate:

import "errors"

result, err := client.Run(req)
switch {
case errors.Is(err, rustbox.ErrAuth):      // 401/403
case errors.Is(err, rustbox.ErrRateLimit): // 429
case errors.Is(err, rustbox.ErrServer):    // 5xx (SDK already retried)
case errors.Is(err, rustbox.ErrTimeout):   // request exceeded timeout
}

🧰 Full API

Method	Returns
rustbox.New(apiKey, opts ...Option)	*Client (empty apiKey panics)
WithBaseURL(url)	Option
WithHTTPClient(h)	Option
WithMaxRetries(n)	Option
client.Run(req)	(map[string]any, error)
client.Submit(req, wait, opts...)	(map[string]any, error)
client.GetResult(id)	(map[string]any, error)
client.GetLanguages()	([]string, error)
client.GetHealth()	(map[string]any, error)
client.GetReady()	(map[string]any, error)

type SubmitRequest struct {
    Language      string `json:"language"`
    Code          string `json:"code"`
    Stdin         string `json:"stdin"`
    Profile       string `json:"profile,omitempty"`        // ProfileJudge | ProfileAgent
    WebhookURL    string `json:"webhook_url,omitempty"`
    WebhookSecret string `json:"webhook_secret,omitempty"`
}

type SubmitOptions struct {
    IdempotencyKey string  // Idempotency-Key header; safe to retry POST when set
}

🧪 Tests

cd sdk/go && go test ./...

httptest.NewServer mocks. No network.

🔗

• 📦 pkg.go.dev: rustbox-sdk/go
• 🪝 Webhooks
• 🛣️ Roadmap
• 🦀 SDK index

Documentation

Overview

Package rustbox is the official Go client for the Rustbox cloud execution sandbox. See https://rustbox.orkait.com/docs.

Index

• Constants
• Variables
• type Client
  • func New(apiKey string, opts ...Option) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) GetHealth() (map[string]interface{}, error)
  • func (c *Client) GetLanguages() ([]string, error)
  • func (c *Client) GetReady() (map[string]interface{}, error)
  • func (c *Client) GetResult(id string) (map[string]interface{}, error)
  • func (c *Client) Run(req SubmitRequest) (map[string]interface{}, error)
  • func (c *Client) Submit(req SubmitRequest, wait bool, opts ...SubmitOptions) (map[string]interface{}, error)
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithMaxRetries(n int) Option
• type SubmitOptions
• type SubmitRequest

Constants

const (
	ProfileJudge = "judge"
	ProfileAgent = "agent"
)

Profile selects the execution profile.

• ProfileJudge ("judge", default): short evaluation runs.
• ProfileAgent ("agent"): longer jobs with egress proxy + per-key byte budgets. Requires a non-trial API key.

const DefaultBaseURL = "https://rustbox-api.orkait.com"

DefaultBaseURL is the production Rustbox endpoint.

const DefaultMaxRetries = 2

DefaultMaxRetries is the retry attempt budget on transient failures (5xx, network).

const DefaultTimeout = 65 * time.Second

DefaultTimeout is the per-request HTTP timeout if WithHTTPClient is not used.

const Version = "0.1.0"

Version of this SDK. Sent in User-Agent.

Variables

var (
	ErrAuth      = errors.New("rustbox: invalid or missing API key")
	ErrRateLimit = errors.New("rustbox: rate limit exceeded")
	ErrServer    = errors.New("rustbox: server error")
	ErrTimeout   = errors.New("rustbox: request timed out")
)

Sentinel errors. Use errors.Is to discriminate on Run/Submit/etc results.

Types

type Client

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

Client holds API credentials + transport. Construct with New(...). Fields are unexported - use Option arguments to configure.

func New

func New(apiKey string, opts ...Option) *Client

New creates a Client. apiKey is required and must be non-empty.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL exposes the configured base URL (read-only accessor).

func (*Client) GetHealth

func (c *Client) GetHealth() (map[string]interface{}, error)

func (*Client) GetLanguages

func (c *Client) GetLanguages() ([]string, error)

func (*Client) GetReady

func (c *Client) GetReady() (map[string]interface{}, error)

func (*Client) GetResult

func (c *Client) GetResult(id string) (map[string]interface{}, error)

func (*Client) Run

func (c *Client) Run(req SubmitRequest) (map[string]interface{}, error)

Run submits + waits + auto-polls until verdict. Auto-generates an Idempotency-Key so the underlying POST is safe to retry on transient failure.

func (*Client) Submit

func (c *Client) Submit(req SubmitRequest, wait bool, opts ...SubmitOptions) (map[string]interface{}, error)

Submit sends a job. Set wait=true for sync execution (server polls internally up to RUSTBOX_SYNC_WAIT_TIMEOUT_SECS).

type Option

type Option func(*Client)

Option configures a Client. Pass to New as variadic args.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default API base URL. Use for staging.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient overrides the default HTTP client (DefaultTimeout).

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets retry attempt budget on transient failures. Default: DefaultMaxRetries.

type SubmitOptions

type SubmitOptions struct {
	// IdempotencyKey, if non-empty, is sent as Idempotency-Key header.
	// Safe to retry POST /api/submit when set.
	IdempotencyKey string
}

SubmitOptions are per-request knobs that don't belong in the request body.

type SubmitRequest

type SubmitRequest struct {
	Language string `json:"language"`
	Code     string `json:"code"`
	Stdin    string `json:"stdin"`
	// Profile is "judge" (default if empty) or "agent". See Profile* consts.
	Profile string `json:"profile,omitempty"`
	// WebhookURL + WebhookSecret enable HMAC-signed callback delivery.
	// Server POSTs the result to WebhookURL when the job finishes.
	WebhookURL    string `json:"webhook_url,omitempty"`
	WebhookSecret string `json:"webhook_secret,omitempty"`
}