korbit

type Built ¶

type Built struct {
	Method  string
	URL     string
	Headers map[string]string
	Body    string
}

Built is a fully-formed HTTP request, ready to send or display (dry-run).

func Build(r Request, opts Options) Built

type Call ¶

type Call struct {
	Method    string
	Path      string
	Params    []KV
	Auth      bool
	TimeoutMs int
}

Call is one logical API call, pre-signing. TimeoutMs overrides the client's per-attempt timeout for this call (0 = client default).

type CallInfo ¶

type CallInfo struct {
	Origin   Origin
	Method   string
	Path     string
	BaseURL  string
	Auth     bool
	KeyName  string // the named key signing this call ("" for public calls)
	APIKeyID string // the public api-key id ("" for public calls)
	// Safety is the read/write class when this call belongs to an operation; the
	// journaling policy reads it to record writes and skip reads. Empty for an
	// ad-hoc call, where Method classifies it instead.
	Safety cmdmeta.Safety
	// ParamsJSON is the pre-signing params as a JSON object (wire param names →
	// values), or nil/empty when there are none. Pre-signing ONLY: never carries
	// timestamp/recvWindow/signature.
	ParamsJSON []byte
}

CallInfo describes one logical call for the journal seam, captured BEFORE signing. It deliberately carries only non-secret, pre-signing facts: ParamsJSON must be the request's pre-signing params — the timestamp, recvWindow, and signature are appended inside Build AFTER CallInfo is built, so they never reach a Recorder. The private key is never present.

type Client ¶

type Client struct {
	// BaseURL is the API host (e.g. https://api.korbit.co.kr). Required.
	BaseURL string
	// Doer performs the HTTP request; nil uses http.DefaultClient.
	Doer Doer
	// Creds sign private calls; nil = public-only (a Call with Auth true then
	// fails fast).
	Creds *Credentials
	// UserAgent overrides the User-Agent header; "" keeps the default
	// ("korbit-cli/<version>"). Composing it is the caller's job (see Options.UserAgent).
	UserAgent string
	// Clock is the shared server-clock estimate this client signs against; nil =
	// sign with the local wall clock. Wire it to one clock.State (via
	// clock.Syncer.State) so a single estimate covers every surface.
	Clock Clock
	// Resync re-measures the server clock; it is the ONE resync primitive (wire
	// it to clock.Syncer.Sync). On EXCEED_TIME_WINDOW (when the policy retries the
	// pre-execution class) Do calls Resync once, then re-signs reading the now
	// corrected Clock. nil = no auto-correct: EXCEED_TIME_WINDOW is then surfaced,
	// not retried (the public and doctor surfaces leave it nil).
	Resync func() error
	// TimeoutMs is the per-attempt HTTP timeout; 0 = the package default (15s).
	// A Call may override it per call.
	TimeoutMs int
	// Sleep is the inter-retry delay primitive; nil = time.Sleep. (Do also makes
	// the wait context-aware regardless — see Do.)
	Sleep func(time.Duration)
	// Observe receives short retry-decision descriptions for --debug; nil = off.
	Observe func(string)
	// NewRecorder mints a FRESH per-call journal Recorder for one Do (reading the
	// active operation from ctx and the call's params), so concurrent calls never
	// share recorder state. nil — or a nil Recorder returned — means this call is
	// not recorded.
	NewRecorder func(ctx context.Context, call Call) Recorder
	// Origin attributes calls to a frontend; flows into CallInfo.
	Origin Origin
	// KeyName / APIKeyID are recorded into CallInfo (the public key id; never a
	// secret). APIKeyID is informational for the recorder — Creds.APIKeyID is
	// what actually signs.
	KeyName  string
	APIKeyID string
	// Log is the optional operational logger for this client's wire activity
	// (request target/timing/attempt at Debug, a network error about to be
	// retried at Warn). nil = silent. It NEVER receives a secret, signature, or
	// raw response body — only the method, path, host, status, and symbolic code.
	Log *slog.Logger
}

Client is the single front door for calling Korbit: the L1 transport that signs REST calls and the WebSocket upgrade (SignHandshake), runs exactly the retry Policy it is HANDED (the zero Policy is a single shot), owns its clock (read via Clock, resync via Resync), and records each call through a per-call Recorder it mints itself. It holds NO call policy of its own — callers (L2 ops, frontends) decide the policy per call. See doc.go for the package-level contracts.

A Client is configured once and reused; Do is safe for concurrent use as long as the injected Clock/Resync/Sleep/Observe/NewRecorder are. NewRecorder mints a fresh per-call Recorder for every Do, so a shared Client has no shared mutable recording state.

func (c *Client) Do(ctx context.Context, call Call, pol Policy) (json.RawMessage, Meta, error)

func (c *Client) ServerNowMs() int64

func (c *Client) SignHandshake() (string, error)

type Clock ¶

type Clock interface {
	// SignNow is the corrected, lean-adjusted unix-ms timestamp to sign with.
	SignNow() int64
	// RecvWindowMs is the widened signed-request validity window in ms, 0 = omit
	// (server default 5s). One value for every surface (omit-below-5s).
	RecvWindowMs() int
	// Offset is the raw server−local offset in ms (delivery-delay detection).
	Offset() int64
	// Measured reports whether a server-clock estimate has been installed yet
	// (false = the bare local clock, offset 0). The stream layer's delivery-delay
	// check reads it to decide whether a suspected delay against an unmeasured
	// clock warrants a one-off reactive resync — otherwise a skewed local clock
	// masquerades as delivery lag.
	Measured() bool
	// ServerNowMs is the clock's best estimate of the server's current unix-ms
	// time (the local clock plus the raw Offset, UN-leaned — unlike SignNow,
	// which leans into the past for the signing bound). It is the source for
	// defaulting server-relative lookback windows sent on the wire (the history
	// walk's start). It reads the same local-clock seam the estimate was measured
	// against, so it honors a test clock.
	ServerNowMs() int64
}

Clock is the read view of the shared server-clock estimate a Client signs against (and that the stream reads for delivery-delay detection). It is an interface so package korbit does not import internal/clock — clock.State satisfies it structurally, preserving the no-import-cycle invariant in both packages' doc.go. Resync (the measurement that updates the estimate) is NOT on this read-only view; it is Client.Resync, so a client can sign against a clock without being able to auto-correct it (the doctor surface signs with a raw, never-resynced clock to surface skew).

type ClockOffset ¶

type ClockOffset struct {
	OffsetMs int64
	RTTMinMs int64
	Samples  int
}

ClockOffset is the result of measuring the local clock against Korbit's server clock. OffsetMs is the best estimate of (serverClock - localClock): add it to a local timestamp to get the server's notion of "now". RTTMinMs is the smallest round-trip seen across the probes; the estimate's uncertainty is about ±RTTMinMs/2 (the unmodelable path asymmetry), so callers that must not overshoot the server's tight future bound lean their corrected timestamp into the past by that much. Samples is how many probes succeeded.

func MeasureClockOffset(opts Options, probes int, log *slog.Logger) (ClockOffset, error)

offset_i = serverTime_i - (t0_i + t1_i)/2
rtt_i    = t1_i - t0_i

func (o ClockOffset) UncertaintyMs() int64

type Correction ¶

type Correction struct {
	Now          func() int64
	RecvWindowMs int
}

Correction is the clock adjustment to install on a corrective EXCEED_TIME_WINDOW retry. Now, when non-nil, REPLACES opts.Now with a corrected clock (the server-clock estimate, already leaned into the past by the measurement uncertainty) — it replaces rather than composes, so a request whose clock was already corrected proactively by --time-sync on is not double-adjusted. RecvWindowMs, when > 0, widens the signed-request validity window so the leaned timestamp still lands inside it on a slow/asymmetric link.

type Credentials ¶

type Credentials struct {
	APIKeyID string
	Signer   Signer
}

Credentials sign a private request: the api-key id sent as X-KAPI-KEY and the Signer that produces the `signature` value (ED25519 or HMAC-SHA256).

type Decision ¶

type Decision struct {
	Action RetryAction
	Wait   time.Duration
	Reason string
}

Decision is what the ladder permits for one failed attempt. Wait is set only for RetryWait. Reason is a short human description for --debug Observe, and is "" when the caller supplies its own message (RetryResync) or the class is surfaced silently (a policy-gated or fatal give-up).

type Doer ¶

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer performs an HTTP request. *http.Client satisfies it; tests inject a stub.

type IPProber ¶

type IPProber func(ctx context.Context, network, baseURL, userAgent string, timeoutMs int) (string, error)

IPProber fetches the caller's public IP from baseURL over a specific network family ("tcp4" or "tcp6") and returns the trimmed plaintext IP. Forcing the family is what lets the CLI report both the IPv4 and the IPv6 address Korbit sees you from, so an agent can allowlist whichever family it will connect over. It is a seam: the default dials the real network (the cli builds it over netbind.FamilyDoer); tests inject a stub. The userAgent is the caller-composed User-Agent; an empty string falls back to the bare "korbit-cli/<version>".

type KV ¶

type KV struct {
	Key   string
	Value string
}

KV is one ordered API parameter. Order is preserved through signing.

type Keypair ¶

type Keypair struct {
	PublicPEM  string
	PrivatePEM string
}

Keypair is a generated ED25519 keypair in PEM form. The public key is SPKI; the private key is PKCS#8.

func GenerateKeypair() (Keypair, error)

type Meta ¶

type Meta struct {
	Attempts     int
	StartedAtMs  int64
	FinishedAtMs int64
	RecordID     int64
}

Meta reports how a Do executed. A post-call journal-write failure is NOT here: the Recorder delivers it through its own sink (callrec's onPostFailure), never back through Do — so a journal fault can never be conflated with the API error.

type Options ¶

type Options struct {
	BaseURL    string
	RecvWindow int // 0 = omit
	TimeoutMs  int
	Creds      *Credentials
	Doer       Doer
	Now        func() int64
	// UserAgent overrides the User-Agent header. Empty string keeps the default
	// ("korbit-cli/<version>"). Composing a richer string (program version, OS,
	// Origin) is the CALLER's job at wiring time. This package gathers no OS
	// info; it only carries the seam.
	UserAgent string
}

Options configures request building and execution.

type Origin ¶

type Origin struct {
	// Surface is the frontend identity, one of the Surface* constants below.
	Surface string
	// Detail is optional finer attribution (e.g. a sub-command), free-form.
	Detail string
}

Origin attributes a logical call to the frontend that issued it: which Surface a Client acts for, with an optional finer Detail. It flows into CallInfo (the recorder seam); the journal `origin` column is reserved and not written.

type Outcome ¶

type Outcome struct {
	// Err is the error Do is about to return (nil on success).
	Err error
	// HTTPStatus is the final HTTP status observed (0 if no response was
	// received — a pre-response transport failure).
	HTTPStatus int
	// Code is the symbolic error code on an API rejection ("" otherwise).
	Code string
	// Message is a short human description of the failure ("" on success).
	Message string
	// Attempts is the number of underlying sends this logical call took.
	Attempts int
	// StartedAtMs / FinishedAtMs bracket the whole logical call (all attempts),
	// in unix ms; DurationMs is their difference for convenience.
	StartedAtMs  int64
	FinishedAtMs int64
	DurationMs   int64
}

Outcome is the post-call result handed to Recorder.Record. Exactly one of the success/error shapes is meaningful: on success Err is nil and HTTPStatus is the 2xx seen; on failure Err is the surfaced error and Code/HTTPStatus/Message describe it (from the ApiError when the failure was an API rejection).

type Policy ¶

type Policy struct {
	// Idempotent gates the FULL retry ladder exactly as RetryPolicy.Idempotent:
	// when true the ambiguous class (network/5xx) is retried with backoff, and
	// the pre-execution classes too.
	Idempotent bool
	// RetryPreExec, when true, retries ONLY the provably-pre-execution classes —
	// EXCEED_TIME_WINDOW (one corrective resync) and HTTP 429 (Retry-After /
	// backoff within budget) — even when !Idempotent. The ambiguous classes
	// (network/5xx) are NOT retried unless Idempotent. It exists for the L2
	// reconcile path.
	RetryPreExec bool
	// BudgetMs bounds total inter-retry SLEEP (the corrective EXCEED_TIME_WINDOW
	// resync does not draw it down). 0 disables the budgeted (sleeping) classes;
	// the no-sleep corrective retry still runs when its gate allows.
	BudgetMs int
}

Policy is the per-call retry policy — INPUT decided by the caller (L2 ops or a frontend), never by the Client. The zero value is a single shot (the fail-safe default, identical to the RetryPolicy zero value).

type Recorder ¶

type Recorder interface {
	// Ready is the pre-send gate, called once BEFORE the first send of a call
	// that will be recorded. An error aborts the call with nothing on the wire,
	// preserving the open-journal-before-send hard guarantee (e.g. a read-only
	// home fails at this point, having sent nothing). Returning nil permits the
	// send.
	Ready(info CallInfo) error
	// Record is the post-call write, called exactly once after the logical call
	// completes (success or failure) with the attempt count folded in — one
	// logical Do == one record, one api_calls row per call. recordID is the
	// stored row id (0 when not applicable). A write failure is NOT returned: the
	// Recorder routes it through its own sink (see the severity contract above).
	Record(info CallInfo, out Outcome) (recordID int64)
}

Recorder is the journal seam for the L1 client. It is an interface here on purpose: package korbit must NOT import internal/journal (that would invert the layering and pull SQLite into the wire layer). A frontend supplies the concrete Recorder.

Severity contract: the Recorder — not Client.Do — decides fail-vs-warn, and it delivers a POST-call failure entirely through its own sink (callrec's onPostFailure), never back through Do. So Record cannot return an error: a broken journal at write time is the Recorder's to surface (warn, toast, or capture-for-fatal), keeping the API error and the journal error on strictly separate channels. The only failure the client honors is a PRE-send Ready error, which aborts with nothing on the wire (the hard guarantee).

type Request ¶

type Request struct {
	Method string
	Path   string
	Params []KV
	Auth   bool
}

Request is a logical API call before signing.

type RetryAction ¶

type RetryAction int

RetryAction is the mechanical decision Next returns.

const (
	// RetryGiveUp: surface the error — not retryable under this policy, the
	// budget is exhausted, or no further clock correction is available.
	RetryGiveUp RetryAction = iota
	// RetryResync: perform the ONE clock resync (no sleep, does not draw down the
	// budget), then retry. Returned at most once per governor, only for
	// EXCEED_TIME_WINDOW when a resync hook is available.
	RetryResync
	// RetryWait: sleep Wait, then retry.
	RetryWait
)

func (a RetryAction) String() string

type RetryClass ¶

type RetryClass int

RetryClass is the four-way classification of an Execute error, exported so the L2 ops layer (order-place reconcile, history walking) can reason about whether a failed call can have had side effects.

The classes split into two groups by side-effect provability:

• the PRE-EXECUTION group — {ClassTimeWindow, ClassRateLimited} — the server provably rejected the request at a gate (its clock window, or rate limiter) BEFORE any side effect. Resending is always safe, even for a money mover. This is the group RetryPreExec retries.
• the AMBIGUOUS group — {ClassTransient} — a network/transport failure or an HTTP 5xx: the request MAY have executed (the response was lost). Only an idempotent request may be blindly resent; otherwise the caller must reconcile (the L2 reconcile protocol consumes exactly this distinction). The TRY_AGAIN cancel "retry shortly" condition is also routed to ClassTransient — not because it is ambiguous (it is side-effect-free) but because it wants the same idempotent-only backoff retry.
• ClassFatal — any other API rejection (4xx other than 429, success:false): resending cannot help, so it is surfaced immediately.

Use IsPreExecution / IsAmbiguous to query the grouping by name.

const (
	// ClassFatal is a non-retryable failure: surface it.
	ClassFatal RetryClass = iota
	// ClassTimeWindow is EXCEED_TIME_WINDOW — pre-execution; resync the clock
	// and retry.
	ClassTimeWindow
	// ClassRateLimited is HTTP 429 — pre-execution; honor Retry-After else back
	// off.
	ClassRateLimited
	// ClassTransient is retried with exponential backoff, and only for an
	// idempotent request. Its members: a network/transport error or HTTP 5xx —
	// AMBIGUOUS (may have executed), which is exactly why the idempotency gate
	// matters — and the TRY_AGAIN "order is being processed, retry shortly"
	// cancel condition, which is side-effect-free and cancel-only (so it always
	// satisfies the gate) but shares the same backoff-retry mechanics.
	ClassTransient
)

func Classify(err error) RetryClass

func (c RetryClass) IsAmbiguous() bool

func (c RetryClass) IsPreExecution() bool

func (c RetryClass) String() string

type RetryGovernor ¶

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

RetryGovernor is the ONE retry ladder shared by the budgeted retry loops in the tree — the L1 retryEngine (here) and the L2 order-place reconcile loop (placeOp.runReconcile). It encapsulates the whole ladder policy: the four-class taxonomy's mechanics, the exponential backoff schedule, the HTTP 429 Retry-After honor, the single no-sleep EXCEED_TIME_WINDOW corrective retry, the total sleep budget, and the hard iteration ceiling (the structural backstop). It performs NO I/O — it never sleeps, resyncs, or sends. The caller drives its own loop and, per failed attempt, asks Next what the ladder permits, then carries out the returned action with its own sleep/resync mechanism. This keeps the policy in one place while each caller keeps its own control-flow shell: the engine drives a send func and surfaces errors directly, whereas the reconcile loop interleaves DUPLICATE-resolution and the eventual-consistency endgame, mapping each give-up class to its own clean-fail vs UNKNOWN semantics.

The two policy axes select which classes are retried:

• idempotent: when true, the ambiguous class (network/5xx) is retried with backoff (the idempotency gate).
• retryPre: when true, the pre-execution classes (EXCEED_TIME_WINDOW via one corrective resync, HTTP 429 via Retry-After/backoff) are retried even when !idempotent.

When neither axis applies to a class that class is surfaced (RetryGiveUp); when neither applies at all the loop is effectively a single shot.

The reconnect loop (stream.connManager.run) deliberately does NOT use a governor: it is unbounded by design (a resilient stream reconnects forever), has no sleep budget, and classifies handshake rejections rather than Classify errors, so its safety is a pure rate bound (always back off) — a structurally different shape. See the "Loop-safety invariants" section of doc.go.

func NewRetryGovernor(idempotent, retryPre, canResync bool, budgetMs int64) *RetryGovernor

func (g *RetryGovernor) Attempt() bool

func (g *RetryGovernor) Attempts() int

func (g *RetryGovernor) Next(class RetryClass, retryAfterMs int64) Decision

type RetryPolicy ¶

type RetryPolicy struct {
	// Idempotent is the master gate. When false, ExecuteWithRetry sends exactly
	// once and surfaces the first error, no matter its kind — so money-moving
	// writes and order placement are never auto-resent on an ambiguous failure.
	// Only GET endpoints and explicitly-idempotent writes (cancel, deposit
	// address generate) set this true.
	Idempotent bool
	// BudgetMs bounds the total time the layer will spend SLEEPING between
	// retries (the sum of backoff/Retry-After waits). Each attempt additionally
	// keeps its own opts.TimeoutMs; the corrective EXCEED_TIME_WINDOW retry does
	// not sleep and so does not draw down the budget. 0 disables retry entirely
	// (single shot) even when Idempotent. Tracking scheduled sleep rather than a
	// wall clock keeps the layer deterministic and testable without a fake clock.
	BudgetMs int
	// Correct re-measures the clock for the one corrective retry after an
	// EXCEED_TIME_WINDOW rejection. nil means no correction is available, in
	// which case EXCEED_TIME_WINDOW is treated as a normal (non-corrective)
	// failure and not retried. Called at most once per ExecuteWithRetry.
	Correct func() (Correction, error)
	// Sleep is the delay between retries; injectable for tests. Defaults to
	// time.Sleep.
	Sleep func(time.Duration)
	// Attempts, when non-nil, is incremented once per underlying Execute call
	// (including the single-shot path and the first attempt), so the caller can
	// record how many sends a request actually took. retries = *Attempts - 1.
	Attempts *int
	// Observe, when non-nil, is called with a short human description each time a
	// failed attempt leads to a retry decision (a retry, or giving up because the
	// budget is exhausted) — for --debug diagnostics. Not called on success or a
	// non-retryable (fatal) failure, which the caller surfaces directly.
	Observe func(string)
}

RetryPolicy configures ExecuteWithRetry. The zero value (Idempotent false / BudgetMs 0) is a single shot — identical to calling Execute directly — which is the deliberate fail-safe default for any request that must not be resent.

type Signer ¶

type Signer interface {
	Sign(encodedParams string) string
}

Signer produces the value of the `signature` parameter for an encoded parameter string, the way the server verifies it. It is the abstraction over the supported key types: ED25519 returns a base64 detached signature, HMAC-SHA256 a lowercase-hex MAC. Both sign EXACTLY the bytes the caller sends, so a Signer must never re-encode its input. A Signer carries secret material, so it redacts itself under every fmt verb — it rides inside Credentials, which diagnostics may render.

func NewEd25519Signer(key ed25519.PrivateKey) Signer

func NewHMACSHA256Signer(secret []byte) Signer