Documentation
¶
Overview ¶
Package api wraps the Hadron GraphQL endpoint: a genqlient client for typed operations, a raw escape hatch for `hadron api`, and the mapping from transport/GraphQL errors to exit codes.
Index ¶
- Constants
- func CollectAll[T any](fetch func(limit, offset int) ([]T, int, error)) ([]T, error)
- func CollectNodeBatch(ids []string, ...) ([]*gen.NodeBatchNodeBatchNodeBatchResultNodesNode, []string, error)
- func CollectUntil[T any](fetch func(limit, offset int) ([]T, int, error), done func(items []T) bool) ([]T, error)
- func DescendantCount(err error) int
- func DocumentFromBatchNode(n *batchNode) *nodedoc.Document
- func Endpoint(serverURL string) string
- func HasErrorCode(err error, code string) bool
- func MapError(err error) error
- func NewClient(serverURL, token string, httpClient *http.Client) (graphql.Client, error)
- func RequireSecureURL(serverURL, token string) error
- type FindNodesPage
- type ListNode
- type RawResult
- type SearchHit
- type SearchNode
- type SearchPage
Constants ¶
const EnvAllowHTTP = urlsec.EnvAllowHTTP
EnvAllowHTTP opts out of the HTTPS-enforcement guard for a trusted local or self-hosted server (set to "1").
const NodeBatchCap = 200
NodeBatchCap mirrors hadron-server's BATCH_READ_MAX_NODES (cor:api:040): a single nodeBatch call accepts at most 200 ids and fails loud above that, so bulk reads fan out in fixed-size chunks. The server also enforces a ~1 MB response cap that can return a partial page (truncated=true) with the spillover ids in `omitted`; CollectNodeBatch re-requests those.
const PageLimit = 200
PageLimit is the server's hard cap on a single page of the uniform paginated list queries (hadron-server#473: limit default 50, cap 200).
Variables ¶
This section is empty.
Functions ¶
func CollectAll ¶ added in v0.5.1
CollectAll drains a uniform paginated { items, total } list query (hadron-server#473) to exhaustion, so "whole scope" commands never silently truncate at one server page. fetch receives (limit, offset) and returns one page's items plus the envelope total.
func CollectNodeBatch ¶ added in v0.2.0
func CollectNodeBatch( ids []string, fetch func([]string) (*gen.NodeBatchNodeBatchNodeBatchResult, error), ) ([]*gen.NodeBatchNodeBatchNodeBatchResultNodesNode, []string, error)
CollectNodeBatch fetches full nodes for ids in cap-sized chunks, re-queuing the spillover the server drops under its response-size cap. fetch is injected rather than calling gen.NodeBatch directly so the chunking/truncation loop is unit-testable without a server and so each caller controls the field projection. Returns the nodes (input order is not preserved across chunks), the union of ids the server reported unavailable, and the first error.
Shared by the whole-corpus fan-outs (`memory export`, `spec get --prefix`).
func CollectUntil ¶ added in v0.5.1
func CollectUntil[T any](fetch func(limit, offset int) ([]T, int, error), done func(items []T) bool) ([]T, error)
CollectUntil is CollectAll with an early exit: after each page, done receives the items accumulated so far, and returning true stops paging (the accumulated items are returned as-is). Use it when a caller can tell mid-scan that it already has what it needs — e.g. an exact match in a sorted list — without draining the remaining pages.
func DescendantCount ¶ added in v0.8.0
DescendantCount returns the descendant count carried by a NODE_HAS_DESCENDANTS error (server #661: its extensions.count), or -1 when err is not that error or carries no non-negative numeric count. JSON numbers decode to float64, but a few other numeric shapes are tolerated. A negative or non-numeric value is treated as "no count" (-1) so callers never render a nonsensical "-N descendant(s)". Call it BEFORE MapError wraps the error.
func DocumentFromBatchNode ¶ added in v0.3.0
DocumentFromBatchNode maps a bulk-read node into the neutral nodedoc.Document the markdown/JSON codecs consume. It is the single gen→Document mapping shared by `memory export` and `node export`. Type "" carries the server default (info), so it never serializes and a re-import defaults correctly. The projection only carries the memory id, not the URN, so callers that emit a standalone file resolve and set Document.MemoryURN themselves.
func HasErrorCode ¶ added in v0.5.1
HasErrorCode reports whether err carries a GraphQL error whose extensions.code equals code. It inspects the raw genqlient error (call it BEFORE MapError wraps the error into a CodedError) so callers can branch on a specific server error — e.g. `node import` falling back from updateNode's NODE_NOT_FOUND to createNode.
func MapError ¶
MapError converts transport and GraphQL errors into CodedErrors so the root command can derive the documented exit code. Codes come from hadron-server's Apollo resolvers (extensions.code).
func NewClient ¶
NewClient returns a genqlient client for the given server, authenticating with token (may be empty for anonymous calls).
func RequireSecureURL ¶ added in v0.6.0
RequireSecureURL refuses to transmit the bearer token over a non-https server URL — cleartext credentials are trivially captured by an on-path attacker on the shared CI/dev machines this CLI runs on (#114). Carve-outs: a loopback host (local dev, incl. the test httptest servers) and HADRON_ALLOW_HTTP=1 (a trusted self-hosted backend). An empty token means no credential rides, so the check is a no-op — anonymous http is allowed.
Types ¶
type FindNodesPage ¶ added in v0.5.0
FindNodesPage is the flattened result of one findNodes call: the hit nodes (hits[].node hoisted to a bare slice, the shape every old `nodes`/`nodeSearch` caller expects), plus the envelope's total and the degraded/reason notes that `spec find` surfaces on a vector-less memory. Nodes is always non-nil.
func FindNodes ¶ added in v0.5.0
func FindNodes( ctx context.Context, client graphql.Client, query *string, mode *gen.FindNodesMode, filter *gen.NodeFilter, sort *gen.NodeSort, sortProperty *gqltypes.NodePropertySort, limit, offset *int, ) (*FindNodesPage, error)
FindNodes runs the unified node search/list (cor:api:090) and flattens the hits[].node envelope into a bare node slice. Omit query for a filtered list in deterministic order (the old `nodes` semantics); pass query + mode to rank (the old `nodeSearch`). sortProperty orders by a properties/data JSON path and overrides sort when set (#719). All args are optional; nil pointers are omitted from the wire so the server applies no constraint. The caller maps GraphQL errors through MapError as usual.
type ListNode ¶ added in v0.5.0
type ListNode = gen.FindNodesFindNodesFindNodesResultHitsNodeHitNode
ListNode is the shallow node projection the unified `findNodes` field returns under hits[].node — id/loc/name/type/tags/seq/isRunnable/updatedAt. Aliased here so callers don't spell the deeply-nested genqlient type name (and so a future projection change is a one-line edit), matching the batchNode alias pattern in nodedoc.go.
type RawResult ¶
type RawResult struct {
Body json.RawMessage
Errors []rawError
}
RawResult is the verbatim GraphQL response envelope.
func RawGraphQL ¶
func RawGraphQL(ctx context.Context, serverURL, token, query string, variables map[string]any, httpClient *http.Client) (*RawResult, error)
RawGraphQL posts an arbitrary query/mutation to the server and returns the raw response body. Used by `hadron api`. The returned error carries the mapped exit code when the response contains GraphQL errors.
type SearchHit ¶ added in v0.6.0
type SearchHit struct {
Score *float64
AbstractStale bool
Node *SearchNode
}
SearchHit is one scored search result. Score is nil when the server returned an unscored hit; AbstractStale reports the vector index's abstract-staleness flag (false when absent).
type SearchNode ¶ added in v0.6.0
type SearchNode = gen.SearchNodesFindNodesFindNodesResultHitsNodeHitNode
SearchNode is the search-shaped node projection (abstract included).
type SearchPage ¶ added in v0.6.0
SearchPage is the scored counterpart of FindNodesPage: it preserves per-hit scores rather than flattening to bare nodes.
func SearchNodes ¶ added in v0.6.0
func SearchNodes( ctx context.Context, client graphql.Client, query string, mode *gen.FindNodesMode, filter *gen.NodeFilter, sortProperty *gqltypes.NodePropertySort, limit, offset *int, ) (*SearchPage, error)
SearchNodes runs a ranked findNodes query (the `hadron search` backend), keeping per-hit score + vector metadata that FindNodes drops. sortProperty orders by a properties/data JSON path and overrides the mode ranking window when set (#719); nil pointers are omitted from the wire.
Source Files
Directories