Documentation
¶
Overview ¶
Package hrana is a bounded client for the official libSQL Hrana 3 pipeline protocol. It is private to the dalgo2libsql adapter.
One call sends a stateless pipeline — an execute request and a close request, with no baton — and decodes every result before returning any value, so a server that answers a later request with an error can never look like a successful read. Nothing here exposes a baton, a raw endpoint URL, credentials, or a request body to a caller's error chain.
Index ¶
Constants ¶
const ( DefaultMaxRequestBytes = 1 << 20 // 1 MiB DefaultMaxResponseBytes = 4 << 20 // 4 MiB DefaultMaxOperationBytes = 16 << 20 // 16 MiB DefaultMaxOperationReqs = 32 DefaultMaxRows = 10_000 DefaultMaxOperationRows = 50_000 DefaultMaxColumns = 256 DefaultMaxValueBytes = 1 << 20 // 1 MiB DefaultMaxArgs = 256 DefaultMaxStatementBytes = 1 << 20 AbsoluteMaxRequestBytes = 64 << 20 AbsoluteMaxResponseBytes = 64 << 20 AbsoluteMaxOperationBytes = 64 << 20 AbsoluteMaxOperationReqs = 256 AbsoluteMaxRows = 100_000 AbsoluteMaxOperationRows = 500_000 AbsoluteMaxColumns = 2_048 AbsoluteMaxValueBytes = 16 << 20 AbsoluteMaxArgs = 4_096 AbsoluteMaxStatementBytes = 16 << 20 )
Default and absolute limits. The defaults are deliberately modest: an existing-table read adapter should not buffer an unbounded result.
const Version = "hrana3"
Version identifies the protocol this client speaks.
Variables ¶
var ErrLimit = errors.New("hrana: limit exceeded")
ErrLimit is wrapped by every bound failure.
var ErrProtocol = errors.New("hrana: protocol violation")
ErrProtocol is wrapped by every malformed or unexpected response.
Functions ¶
Types ¶
type Budget ¶
type Budget struct {
// contains filtered or unexported fields
}
Budget is the cumulative accounting of one DALgo operation. The facade attaches one to the context of every read, so the metadata probes the SQL compiler makes and the data statement that follows share one bound.
func BudgetFrom ¶
BudgetFrom returns the budget carried by ctx, or nil.
func NewBudget ¶
NewBudget returns a budget for one operation. Zero limits select the package defaults; NewDB normalizes them once, and this keeps a directly constructed budget from meaning "zero bytes allowed".
func (*Budget) AddRequest ¶
AddRequest records one pipeline call.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is one bounded Hrana 3 pipeline endpoint.
func (*Client) Close ¶
Close releases idle connections of a transport this client owns. It never closes a transport the caller supplied, and it is idempotent.
type Column ¶
Column is one result column. DeclType is SQLite's declared type; it is empty for an expression that has none.
type Config ¶
type Config struct {
// Endpoint is the normalized base URL: https://host[/path]. The client
// appends /v3/pipeline.
Endpoint *url.URL
// HTTPClient is the client to use. New copies the value and, when its
// transport is an *http.Transport, clones that too; the caller's client
// and transport are never mutated. A nil client uses a new default.
HTTPClient *http.Client
// Headers supplies per-request headers, credentials included.
Headers HeaderProvider
// Limits bounds the client and its operations.
Limits Limits
}
Config is the input of New.
type Error ¶
Error is a protocol, transport or limit failure. Its text is safe to return to a caller: it never contains the endpoint, credentials, SQL text, bound values, a response body, or an underlying transport error.
type HeaderProvider ¶
HeaderProvider returns headers for one request. It is called with the request context, which carries the operation's deadline and the per-request cap, so a provider that honours its context cannot outlive the operation.
type Limits ¶
type Limits struct {
// MaxRequestBytes bounds one encoded request body.
MaxRequestBytes int64
// MaxResponseBytes bounds one encoded response body.
MaxResponseBytes int64
// MaxOperationBytes bounds the response bytes of one operation,
// including every internal metadata query it makes.
MaxOperationBytes int64
// MaxOperationRequests bounds the pipeline calls of one operation.
MaxOperationRequests int
// MaxRows bounds the rows of one execute result.
MaxRows int
// MaxOperationRows bounds the rows decoded across one operation.
MaxOperationRows int
// MaxColumns bounds the columns of one execute result.
MaxColumns int
// MaxValueBytes bounds one text or blob cell.
MaxValueBytes int
// MaxArgs bounds the bound arguments of one statement.
MaxArgs int
// MaxStatementBytes bounds one SQL statement string.
MaxStatementBytes int
// Timeout bounds one HTTP request.
Timeout int64 // nanoseconds; kept as int64 so Limits stays comparable
}
Limits bounds one operation. A zero field selects the package default; values above the corresponding absolute maximum are rejected by NormalizeLimits.
func NormalizeLimits ¶
NormalizeLimits returns l with package defaults filled in. It rejects a negative value and a value above the corresponding hard maximum.
Source Files