* fix(httpclient): dial a large batchApply under the server's extended budget bd serve runs an issues:batchApply over largeApplyItemThreshold (100) items under DefaultLargeApplyCeiling (5m) on a context detached from the client, but the wire client capped every request at DefaultTimeout (60s). A large apply on a slow or loaded server therefore failed client-side with "Client.Timeout exceeded while awaiting headers" while the server went on to commit it: an error for an apply that landed. wire.Request.Timeout now raises (never lowers) a bounded client's per-request ceiling for one request, through a shallow copy of the *http.Client that shares its Transport and forced CheckRedirect. ApplyBatch sets it to LargeApplyTimeout (6m) once the plan exceeds LargeApplyItemThreshold. The stall-retry deadline uses the same per-request ceiling. Tests: - wire: a slow fake server times out an at-threshold apply under a short ceiling and completes an over-threshold one; httpClientFor only raises a bounded client and keeps its Transport and CheckRedirect. - httpapi: TestTheClientLargeApplyBudgetCoversTheServer pins the redeclared threshold to the server's and holds LargeApplyTimeout above request read + large-slot wait + ceiling + drain grace (5m45s). - httpclient (served tier): a 101-item apply against a BatchApplier delayed DefaultTimeout+5s, dialed through DialWith + DialOptionsForTarget like the product, commits and returns success (71s). With the raise disabled it fails at 60.03s with Client.Timeout. Ported from bd-enterprise (gascity/bd-enterprise#195). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(httpclient): pin the raised stall-retry deadline; document the 6m large-apply ceiling Review fixups for #7582. - wire: TestARaisedRequestTimeoutAlsoBoundsTheStallRetry pins the one OSS-only hunk of the port, the stall-retry deadline read through httpClientFor(r). Reverting that line to c.hc.Timeout left the whole wire package green; the new case fails on it, because the retry then runs out at the client's own ceiling instead of the request's raised one. - backend/http: Options.HTTPClient said the client is used as given except for redirect handling. A batch apply over 100 items now raises a Timeout shorter than 6 minutes for that request, so the public doc says so. - README and CHANGELOG: the HTTP backend's write bound is no longer 60s for every request. A batch apply over 100 items gets 6 minutes, and a server whose --large-apply-ceiling is raised past about 5m15s can still outlast it. - engdocs/SERVE_RUNBOOK.md: the same limit, next to the stop-grace sizing an operator reads before raising --large-apply-ceiling. - served_batch_apply_test: the race-build comment blamed the client's 60s timeout for shrinking the 1000-item apply. A plan that size now gets wire.LargeApplyTimeout; it stays shrunk because the embedded tier measured it at 903-945s under -race. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
281 lines
14 KiB
Go
281 lines
14 KiB
Go
// Package bdhttp is the public door to the http client store that ships
|
|
// inside this module (internal/httpclient) — the storage backend that speaks
|
|
// the v0 `bd serve` wire to a remote server — for embedders that link beads
|
|
// as a library rather than running cmd/bd.
|
|
//
|
|
// Such an embedder cannot reach the store any other way, for the reason its
|
|
// (hypothetical) postgres sibling would document: the registry facade's
|
|
// Register takes a backends.Backend value whose constructors live in an
|
|
// internal package, and the only other production wiring is cmd/bd's. Without
|
|
// this package a workspace whose .beads/metadata.json names "http" is a
|
|
// workspace an embedder can only tombstone.
|
|
//
|
|
// # Registration is two-step, and that is why Register takes Options
|
|
//
|
|
// Putting "http" in the registry is not enough to open anything: the store
|
|
// dials through a process-wide transport constructor that registration does
|
|
// not install on its own, so a binary that registered and stopped there would
|
|
// fail every open with httpclient.ErrNoTransport — a build-wiring fault, not a
|
|
// workspace or server problem. Register does both: it adds "http" to the
|
|
// registry AND installs the default dialer, and it installs a per-open
|
|
// OpenWith hook so a multi-tenant embedder (for example gc, Gas City — one
|
|
// process serving many workspaces, called "cities") can route a distinct
|
|
// credential through backends.OpenOptions / beads.OpenBestAvailableWith for
|
|
// each workspace it opens, without the process-wide dialer being asked to
|
|
// serve two tenants with one fixed credential.
|
|
//
|
|
// # Credentials: one per open, never one per host
|
|
//
|
|
// A process may open many projects — on one server or several, each with a
|
|
// credential of its own (gc's per-city and per-rig credentials). The rule that
|
|
// keeps them apart: when a credential is handed to an open or a handshake, it
|
|
// is the ONLY credential that open or handshake uses.
|
|
//
|
|
// - Options.Credential (Open, Handshake, Connect) and
|
|
// backends.OpenOptions.Credential carrying a ProvidedCredential (the
|
|
// registry's OpenWith seam, beads.OpenBestAvailableWith) both take this
|
|
// explicit path.
|
|
// - On it no bearer ladder is built, so BEADS_HTTP_TOKEN,
|
|
// BEADS_HTTP_TOKEN_COMMAND and the credentials file (BEADS_CREDENTIALS_FILE,
|
|
// keyed [host:port]) are never read. CA trust comes from Target.CAFile alone
|
|
// (never BEADS_HTTP_CA_FILE), and the plaintext-to-non-loopback grant from
|
|
// Target.AllowInsecureCredential alone (never BEADS_HTTP_ALLOW_INSECURE).
|
|
// The open reads no process environment on the credential's account.
|
|
// - The provider is held by the one store (or the one handshake) it was
|
|
// handed to, and anything it resolves or caches lives there. This package
|
|
// and the one beneath it keep no process-wide credential state: there is no
|
|
// cache keyed by host[:port] for two projects behind the same server to
|
|
// share. (The only process-wide transport state is the CA-scoped
|
|
// *http.Transport pool, keyed by CA file and carrying no credential; the
|
|
// Authorization header is set per request by the store's own provider.)
|
|
//
|
|
// Only with NO credential does an open fall back to the ambient ladder keyed
|
|
// by host[:port] — the single-tenant CLI posture. A multi-tenant embedder
|
|
// should pass a credential on every open, and can make a missing one a loud
|
|
// refusal on the registry seam with Options.RequireCredential. A process-wide
|
|
// credential is refused outright: Register panics on a non-nil
|
|
// Options.Credential, because the dialer it installs serves every workspace.
|
|
//
|
|
// # Stability
|
|
//
|
|
// EXPERIMENTAL, on the same terms as the backend package this sits beside.
|
|
// Pin an exact beads version.
|
|
package bdhttp
|
|
|
|
import (
|
|
"context"
|
|
"net/http"
|
|
|
|
"github.com/steveyegge/beads/backend"
|
|
"github.com/steveyegge/beads/internal/httpapi/apigen"
|
|
"github.com/steveyegge/beads/internal/httpclient"
|
|
"github.com/steveyegge/beads/internal/storage/backends"
|
|
)
|
|
|
|
// UserAgentSuffix identifies this backend inside a stamped User-Agent, so a
|
|
// server log line says both which binary and which client spoke to it. An
|
|
// embedder that stamps its own build joins the two the way cmd/bd does:
|
|
// "myapp/1.4.2 " + bdhttp.UserAgentSuffix.
|
|
const UserAgentSuffix = httpclient.WireUserAgentSuffix
|
|
|
|
// Options configures the transport Register installs and Open/Handshake dial
|
|
// with.
|
|
//
|
|
// The zero value is usable and is what the CLI's own wiring amounts to: the
|
|
// built-in bearer credential ladder (Credential nil), this module's default User-Agent, and
|
|
// the standard http transport.
|
|
type Options struct {
|
|
// UserAgent identifies the embedding build on every request. Empty sends
|
|
// UserAgentSuffix alone, which names the backend but not the binary.
|
|
UserAgent string
|
|
// HTTPClient replaces the transport — a tuned timeout, a proxy, a custom
|
|
// TLS config, an httptest server in a test. Nil builds one. The client is
|
|
// used as given except for two things the underlying wire client always
|
|
// does. It forces redirect handling off: a followed 30x would replay the
|
|
// Authorization header at whatever host the Location named. And for a
|
|
// batch apply of more than 100 items it raises a Timeout shorter than 6
|
|
// minutes to 6 minutes, for that request alone: bd serve gives such a
|
|
// request an extended budget and commits it even after the client has
|
|
// given up, so a shorter Timeout reports a failure for a write that
|
|
// lands. A client with no Timeout stays unbounded; a call's context still
|
|
// bounds it.
|
|
HTTPClient *http.Client
|
|
// RequireCredential makes the registered backend's OpenWith seam refuse a
|
|
// registered open with no OpenOptions.Credential, rather than silently
|
|
// falling back to the ambient bearer ladder (BEADS_HTTP_TOKEN,
|
|
// BEADS_HTTP_TOKEN_COMMAND, the credentials file). It has no effect on
|
|
// Open/Handshake below, or on the plain Open/OpenReadOnly path a
|
|
// single-tenant CLI process uses: both keep the ambient ladder as their
|
|
// documented, legitimate posture.
|
|
//
|
|
// Set this when every caller through beads.OpenBestAvailableWith is a
|
|
// multi-tenant embedder for which ambient, process-global credential
|
|
// state can never safely stand in for one workspace's own — see
|
|
// httpclient.ResolveCredential and backends.OpenOptions.Credential's own
|
|
// doc comment.
|
|
RequireCredential bool
|
|
// Credential, when non-nil, is the ONLY credential Open, Handshake and
|
|
// Connect authorize with: the call reads no ambient token, token command,
|
|
// credentials file, CA env or plaintext env (see the package doc's
|
|
// "Credentials" section and httpclient.DialWithCredential). It is the
|
|
// direct-door twin of backends.OpenOptions.Credential carrying a
|
|
// ProvidedCredential{Provider: Credential}. CA trust on this path is
|
|
// Target.CAFile, and the plaintext grant Target.AllowInsecureCredential.
|
|
//
|
|
// The provider is used by the one store or handshake it is handed to, so
|
|
// whatever it caches is per store. Register refuses (panics on) a non-nil
|
|
// Credential: its dialer is process-wide, and one credential for every
|
|
// workspace is exactly what this field exists to avoid.
|
|
Credential CredentialProvider
|
|
}
|
|
|
|
// Register adds the http store to the backend registry under the name "http"
|
|
// AND installs the transport it dials with, so a workspace whose
|
|
// metadata.json selects the backend opens instead of failing with
|
|
// httpclient.ErrNoTransport.
|
|
//
|
|
// The EMBEDDER calls this explicitly at process start, on the same terms as
|
|
// cmd/bd's own wiring: registration is a property of the distribution being
|
|
// built, not of the import graph. A plain `go build` of an OSS binary that
|
|
// imports this package only transitively, and never calls Register, gains no
|
|
// selectable "http" backend — metadata.json naming it still hard-fails with
|
|
// the registry's UnknownBackendError, exactly as before this package existed.
|
|
//
|
|
// Register panics on a duplicate registration, like any process-start wiring
|
|
// error, so it must have exactly one production call site. Call it once,
|
|
// before any concurrent store access.
|
|
func Register(opts Options) {
|
|
if opts.Credential != nil {
|
|
panic("bdhttp.Register: Options.Credential is per open, not process-wide; pass it to Open/Handshake, or as a ProvidedCredential in backends.OpenOptions")
|
|
}
|
|
base := httpclient.DialOptions{UserAgent: opts.UserAgent, HTTPClient: opts.HTTPClient}
|
|
backends.Register(httpclient.Backend, backends.Backend{
|
|
Open: httpclient.NewFromConfig,
|
|
OpenReadOnly: httpclient.NewReadOnlyFromConfig,
|
|
WorkspaceIsBeadsDir: true,
|
|
Remote: true,
|
|
OpenWith: func(ctx context.Context, beadsDir string, bopts backends.OpenOptions) (backend.DoltStorage, error) {
|
|
return httpclient.OpenWith(ctx, beadsDir, bopts, base, opts.RequireCredential)
|
|
},
|
|
})
|
|
httpclient.RegisterDefaultDialer(base)
|
|
}
|
|
|
|
// Open dials target and returns a store for it, with no workspace on disk.
|
|
//
|
|
// It is the door for an embedder that already knows its server — from its own
|
|
// configuration, or minted per tenant — and would otherwise have to write a
|
|
// .beads directory for the sole benefit of a registry lookup. Registration is
|
|
// not required and does not affect it: Open dials fresh from the Options it is
|
|
// handed. With Options.Credential set, that credential is the only one used, and
|
|
// no ambient credential, CA or plaintext grant is read; without it, Open uses
|
|
// the same built-in bearer ladder Open/OpenReadOnly use.
|
|
//
|
|
// The store carries no local metadata file, which is benign: the two
|
|
// per-user keys it would hold read as unset and write nowhere.
|
|
func Open(ctx context.Context, target Target, opts Options) (backend.DoltStorage, error) {
|
|
base := httpclient.DialOptions{UserAgent: opts.UserAgent, HTTPClient: opts.HTTPClient}
|
|
var conn *httpclient.Conn
|
|
var err error
|
|
if opts.Credential != nil {
|
|
conn, err = httpclient.DialWithCredential(target, opts.Credential, base)
|
|
} else {
|
|
conn, err = httpclient.DialWith(target, httpclient.NewBearerProvider(target.BaseURL), httpclient.DialOptionsForTarget(target, base))
|
|
}
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return httpclient.New(target, conn, nil), nil
|
|
}
|
|
|
|
// Handshake dials target once and returns its startup snapshot, applying the
|
|
// two gates a store applies: api_version equality and, when the target pins
|
|
// one, project identity.
|
|
//
|
|
// It is the pre-connect probe: `bd connect` verifies a server before it
|
|
// writes anything, and it has to do that without opening a store, because the
|
|
// workspace it is about to describe may not select this backend yet. A
|
|
// mismatch comes back as *ProjectMismatchError, which names both ids plus the
|
|
// server's own database and repo root.
|
|
//
|
|
// It dials with the same credentials Open would given the same Options, so a
|
|
// probe can never verify a server the store then cannot reach: Options.Credential
|
|
// when set (and then nothing ambient), else the built-in bearer ladder.
|
|
func Handshake(ctx context.Context, target Target, opts Options) (*ServerSnapshot, error) {
|
|
base := httpclient.DialOptions{UserAgent: opts.UserAgent, HTTPClient: opts.HTTPClient}
|
|
var body *apigen.ContextResponse
|
|
var err error
|
|
if opts.Credential != nil {
|
|
body, err = httpclient.HandshakeWithCredential(ctx, target, opts.Credential, base)
|
|
} else {
|
|
// httpclient.Handshake dials via httpclient.Dial, which binds the
|
|
// same built-in bearer ladder (httpclient.NewBearerProvider) Open
|
|
// uses above.
|
|
body, err = httpclient.Handshake(ctx, target, httpclient.DialOptionsForTarget(target, base))
|
|
}
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return newServerSnapshot(body), nil
|
|
}
|
|
|
|
// ServerSnapshot is what a server says about itself at handshake, curated for
|
|
// this door.
|
|
//
|
|
// It is a struct of its own rather than an alias of the wire document, and
|
|
// the omissions are the point. The wire type is GENERATED from the OpenAPI
|
|
// spec, so aliasing it would make a codegen bump — a field renamed, a member
|
|
// added — a breaking change to a published Go API, decided by a document
|
|
// nobody edits with that in mind. And the document carries facts an embedder
|
|
// has no business depending on: the server's own filesystem paths, its
|
|
// storage mode, its logical database name, the CLI's JSON schema version.
|
|
// Those are the operator's, and several are host paths a multi-tenant caller
|
|
// should not be holding at all.
|
|
//
|
|
// What remains is what a client actually decides with: Capabilities is the
|
|
// field it decides with (an operation is available because the server
|
|
// advertises its token, never because a version string looked new enough),
|
|
// and WireRevision is the revision the handshake already checked against
|
|
// this client's own compiled one before returning a snapshot at all.
|
|
type ServerSnapshot struct {
|
|
// APIVersion is the path major the server serves. The handshake already
|
|
// refused anything this client cannot address, so on a returned snapshot
|
|
// this is confirmation rather than a branch.
|
|
APIVersion string
|
|
// BdVersion is the release of the serving binary. Diagnostic and
|
|
// human-facing: branch on Capabilities, not on this.
|
|
BdVersion string
|
|
// WireRevision is the server's own wire_revision counter (see
|
|
// ContextResponse.WireRevision). The wire handshake itself refuses a
|
|
// server this client build predates (a wire_revision or
|
|
// min_client_wire_revision above wire.ClientWireRevision) before any
|
|
// snapshot is returned, so on a returned snapshot this is exposed for
|
|
// diagnostics, not a branch.
|
|
WireRevision int
|
|
// ProjectID is the workspace identity the server owns. When the Target
|
|
// pinned one, the handshake has already proved they match.
|
|
ProjectID string
|
|
// Capabilities are the operation tokens the server implements. The list
|
|
// grows additively and an operation never appears unless it is fully
|
|
// implemented, which is what makes membership the right question.
|
|
Capabilities []string
|
|
}
|
|
|
|
// newServerSnapshot maps the wire document onto the curated one.
|
|
//
|
|
// The capability slice is copied because the document it comes from is a
|
|
// pointer INTO the wire client's cached handshake, which every later dispatch
|
|
// reads to decide what the server can serve, and whose documented contract is
|
|
// that the caller treats it as read-only.
|
|
func newServerSnapshot(body *apigen.ContextResponse) *ServerSnapshot {
|
|
if body == nil {
|
|
return nil
|
|
}
|
|
return &ServerSnapshot{
|
|
APIVersion: body.ApiVersion,
|
|
BdVersion: body.BdVersion,
|
|
WireRevision: body.WireRevision,
|
|
ProjectID: body.ProjectId,
|
|
Capabilities: append([]string(nil), body.Capabilities...),
|
|
}
|
|
}
|