bit_client

Go client SDK for the bit_tracker service.

A Client is bound to a single project. On Connect it queries the project's current QoS (claims/second budget) and installs a token-bucket rate limiter that throttles Claim calls. The QoS is re-fetched from the server once per minute by a background goroutine. Every request carries a caller-supplied User-Agent.

Install

go get github.com/saveweb/bit_client

Usage

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"bit_client"
)

func main() {
	client, err := bitclient.NewClient(
		bitclient.WithBaseURL("http://127.0.0.1:8835"),
		bitclient.WithProject("myproj_64"),
		bitclient.WithUserAgent("my-worker/1.0"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	ctx := context.Background()
	if err := client.Connect(ctx); err != nil { // fetches QoS, starts refresh loop
		log.Fatal(err)
	}

	for {
		offset, err := client.Claim(ctx) // rate-limited to QoS claims/sec
		if errors.Is(err, bitclient.ErrNoBitsToClaim) {
			break // all done
		}
		if err != nil {
			log.Fatal(err)
		}

		fmt.Println("claimed", offset)

		// ...do work for offset...

		if err := client.Move(ctx, offset, bitclient.FromAuto, bitclient.MapDone); err != nil {
			log.Fatal(err)
		}
	}
}

Methods

Method	Endpoint	Notes
Ping(ctx)	GET /ping	liveness check
QoS(ctx)	GET /proj/:project/qos	always hits server (not cached)
Claim(ctx)	GET /proj/:project/claim	rate-limited to QoS claims/sec
Move(ctx, offset, from, to)	PATCH /proj/:project/move/:offset/:from/:to	from may be a map name or FromAuto

Map name constants: MapTodo, MapWIP, MapFail, MapDone.

Options

• WithBaseURL — default http://127.0.0.1:8835
• WithProject — required
• WithUserAgent — required, sent with every request
• WithHTTPClient — custom *http.Client (default 30s timeout)
• WithQoSRefreshInterval — how often QoS is re-fetched (default 1m)
• WithLogger — custom *slog.Logger (default slog.Default())