Go SDK · Sextant docs

Requires Go 1.22 or later.

Shell

go get sextant.example/sdk

import sextant "sextant.example/sdk"

Client

main.goGo

package main

import (
	"context"
	"errors"
	"log"
	"os"
	"time"

	sextant "sextant.example/sdk"
)

func main() {
	client := sextant.NewClient(os.Getenv("SEXTANT_TOKEN"), sextant.WithURL(os.Getenv("SEXTANT_URL")))

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	job, err := client.Jobs.Create(ctx, &sextant.JobCreateParams{
		Queue:          "emails",
		Handler:        "send-receipt",
		Payload:        map[string]any{"order_id": "ord_4412"},
		IdempotencyKey: "receipt-ord_4412",
	})
	if err != nil {
		log.Fatal(err)
	}

	if _, err := client.Jobs.Cancel(ctx, job.ID); err != nil && !errors.Is(err, sextant.ErrNotFound) {
		log.Fatal(err)
	}
}

Every method takes a context.Context first and returns (result, error). Params are structs; optional fields are pointers or zero values, as documented on each field.

Paging

iter := client.Jobs.List(ctx, &sextant.JobListParams{State: "dead"})
for iter.Next() {
	job := iter.Job()
	fmt.Println(job.ID, job.LastError.Message)
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

Handlers

A handler is a function func(ctx context.Context, job *sextant.Job) error. The context is cancelled on cancellation, timeout and shutdown.

worker.goGo

func main() {
	client := sextant.NewClient("")
	worker := client.Worker(sextant.WorkerOptions{Queues: []string{"emails"}, Concurrency: 20})

	worker.Register("send-receipt", SendReceipt)

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	// Run blocks until ctx is cancelled, then waits for running handlers.
	if err := worker.Run(ctx); err != nil {
		log.Fatal(err)
	}
}

Return sextant.Permanent(err) to move a job straight to dead. Any other error is retried according to the queue policy; see Retries and backoff.

Errors

API errors implement *sextant.APIError with Status, Code, Message and RequestID, and unwrap to sentinels: ErrNotFound, ErrValidation, ErrPermission, ErrConflict, ErrRateLimited.