httpapi

Documentation

Overview

Package httpapi exposes Rostam's vector/RAG operations over a REST/JSON HTTP surface. It is a thin transport over the same op dispatcher the binary TCP server uses: each handler translates a JSON request into the existing ops binary codec, calls Dispatcher.Call, and renders the binary result as JSON. No engine logic lives here — it is a second front door onto the same store, reachable from any language (curl, Python, a LangChain/LlamaIndex adapter).

Index

• func Handler(disp Dispatcher, opts Options) http.Handler
• type AdminBackend
• type Authenticator
• type BackupObject
• type BackupReport
• type Dispatcher
• type Options

Functions

func Handler

func Handler(disp Dispatcher, opts Options) http.Handler

Handler builds the REST router over disp. The routes (all under /v1):

GET    /health                              liveness: the process is serving
GET    /ready                               readiness: every hosted shard can serve
POST   /collections                         create  {name, config}
DELETE /collections/{name}                  drop
POST   /collections/{name}/points           insert/upsert  {id, vector, ...}
POST   /collections/{name}/points/batch     bulk insert/upsert  {upsert, points:[...]}
DELETE /collections/{name}/points/{id}      delete
POST   /collections/{name}/points/batch-get batch get-by-id  {ids:[...], with_vector, with_payload} → {points:[{id,vector,payload,ttl_ms}], missing:[...]} (partial miss = 200, NOT 404)
GET    /collections/{name}/points/{id}      get-by-id  {found, vector, payload, ttl_ms}; ?with_vector/?with_payload
POST   /collections/{name}/points/{id}/payload          merge payload  {...payload...}
POST   /collections/{name}/points/{id}/payload/overwrite replace payload (also PUT .../payload)
POST   /collections/{name}/points/{id}/payload/delete    remove keys    {keys:[...]}
POST   /collections/{name}/points/{id}/payload/clear     empty payload
POST   /collections/{name}/points/search        knn        {query, k, filter}
POST   /collections/{name}/points/search/docs   knn+content
POST   /collections/{name}/points/search/groups group-by-document
POST   /collections/{name}/points/search/hybrid dense+sparse fusion
POST   /collections/{name}/query                unified Query API {root, prefetch:[...], mode:"fusion"|"rerank", method, alpha, rrf_k, k}
POST   /collections/{name}/points/delete        delete-by-filter {filter}
POST   /collections/{name}/resplit             offline resplit {new_partitions}
POST   /collections/{name}/resplit/cleanup     drop orphaned old partitions
POST   /collections/{name}/reshard             online reshard (dual-write, live) {new_partitions}
POST   /collections/{name}/reshard/abort       abort in-flight reshard (pre-cutover)
POST   /multivector/{name}/scroll               MV list live docs {filter, limit, cursor}
POST   /multivector/{name}/resplit             MV offline resplit {new_partitions}
POST   /multivector/{name}/resplit/cleanup     MV drop orphaned old partitions
POST   /multivector/{name}/reshard             MV online reshard (dual-write, live) {new_partitions}
POST   /multivector/{name}/reshard/abort       MV abort in-flight reshard (pre-cutover)
POST   /multivector/{name}/hybrid-search      MV cross-modality hybrid: fuse the MaxSim lane (query token matrix) + the doc sparse lane {query, sparse:{indices,values}, k, method, alpha, filter}
POST   /multivector/{name}/query              MV Query API: MaxSim + sparse prefetch + fusion/rerank {root:{maxsim:[[...]]|sparse:{...},...}, prefetch:[{maxsim|sparse,...}], mode:"fusion"|"rerank", method, alpha, rrf_k, k}
GET    /multivector/{name}/points/{id}         MV get-by-id (tokens+payload)
POST   /multivector/{name}/points/batch-get    MV batch get-by-id {ids:[...], with_vector, with_payload} → {points:[{id,tokens,payload}], missing:[...]} (partial miss = 200, NOT 404)
POST   /multivector/{name}/points/{id}/payload          MV merge payload
POST   /multivector/{name}/points/{id}/payload/overwrite MV replace payload (also PUT)
POST   /multivector/{name}/points/{id}/payload/delete    MV remove keys {keys}
POST   /multivector/{name}/points/{id}/payload/clear     MV empty payload
POST   /named/{name}                           create named-vector collection {named_vectors}
DELETE /named/{name}                           drop
GET    /named/{name}/config                    configured named spaces
POST   /named/{name}/points                    upsert  {id, vectors, metadata, ttl_ms}
DELETE /named/{name}/points/{id}               delete by id (path)
POST   /named/{name}/points/delete             delete by id (body) {id}
POST   /named/{name}/search                    knn over a named space {vector_name, query, k, filter}
POST   /named/{name}/sparse-search             sparse-dot-product top-k over a SPARSE named space {vector_name, query:{indices,values}, k, filter}
POST   /named/{name}/hybrid-search             cross-space hybrid: fuse a dense + a sparse named space {dense_space, dense, sparse_space, sparse:{indices,values}, k, method, alpha, filter}
POST   /named/{name}/query                     named Query API: multi-space prefetch + fusion/rerank {root:{space,dense|sparse,...}, prefetch:[{space,...}], mode:"fusion"|"rerank", method, alpha, rrf_k, k}
POST   /named/{name}/search/docs               knn+payload
POST   /named/{name}/scroll                    list live points {filter, limit}
GET    /named/{name}/points/{id}               named get-by-id (per-space vectors+payload)
POST   /named/{name}/points/batch-get          named batch get-by-id {ids:[...], with_vector, with_payload} → {points:[{id,vectors,payload,ttl_ms}], missing:[...]} (partial miss = 200, NOT 404)
POST   /named/{name}/points/{id}/payload                named merge payload
POST   /named/{name}/points/{id}/payload/overwrite      named replace payload (also PUT)
POST   /named/{name}/points/{id}/payload/delete         named remove keys {keys}
POST   /named/{name}/points/{id}/payload/clear          named empty payload
POST   /aliases                              create alias  {alias, collection} (upsert)
DELETE /aliases/{alias}                       delete alias (idempotent)
GET    /aliases                              list aliases  ?collection=docs filter
POST   /aliases/batch                        atomic batch  {actions:[{create:{alias,collection}}|{delete:{alias}}]}
POST   /admin/keys                           add API key   {token,tenant,scopes,cert_cn} (admin)
DELETE /admin/keys                           revoke key    {token} in BODY, never the path (admin)
GET    /admin/keys                           list keys     redacted {keys:[{fingerprint,tenant,scopes,cert_cn}]} (admin)

Types

type AdminBackend

type AdminBackend interface {
	// BackupNow runs one immediate backup of every live collection and returns one
	// BackupReport per collection (Key empty + Error set on a per-collection
	// failure; the run never aborts on one collection).
	BackupNow(ctx context.Context) ([]BackupReport, error)
	// ListBackups lists every backup snapshot object under the configured tenant
	// prefix.
	ListBackups(ctx context.Context) ([]BackupObject, error)
	// EvictCollection cold-tiers the named collection to the object store (no-op if
	// already cold; error if unknown).
	EvictCollection(ctx context.Context, name string) error
	// RestoreCollection eagerly promotes a cold collection back from the object
	// store (no-op if already hot).
	RestoreCollection(ctx context.Context, name string) error
}

AdminBackend is the OPT-IN object-storage admin surface backing the /v1/admin/backup, /v1/admin/backups, and /v1/collections/{name}/evict|restore REST endpoints. It is implemented in the cmd layer over a *vector.CollectionStore + an objstore.ObjectStore (the SAME shared client the backup cron and cold-tier sweeper use), and threaded in via Options.Admin.

It is deliberately NOT routed through the op Dispatcher: backup/evict/restore need direct access to the collection store and the object store, which the Dispatcher abstraction (op-name + binary args) does not expose. The handlers therefore authorize via the SAME authz gate (the admin op names below classify as admin / fail-closed) and then call this backend directly.

nil (the default, and whenever no bucket/cold-tier is configured) ⇒ the routes are still registered but return 412 Precondition Failed ("object storage not configured"), so an admin call against an un-tiered server fails loud rather than 404-ing or silently no-op'ing.

type Authenticator

type Authenticator = authz.Authenticator

Authenticator authorizes a request. It is the unified RBAC authorizer (authz.Authenticator): each handler builds an authz.AuthRequest{Token, Op, Args} (token from the Bearer header, op + the binary op args it is about to dispatch) and the authorizer derives the (action, resource) and matches the principal's scopes. A nil Authenticator accepts every request (no-auth mode), matching the TCP server's behavior.

type BackupObject

type BackupObject struct {
	Key          string `json:"key"`
	Size         int64  `json:"size"`
	LastModified string `json:"last_modified"`
}

BackupObject is one snapshot object as listed by ListBackups.

type BackupReport

type BackupReport struct {
	Collection string `json:"collection"`
	Key        string `json:"key,omitempty"`
	Size       int64  `json:"size"`
	Error      string `json:"error,omitempty"`
}

BackupReport is one collection's outcome from BackupNow.

type Dispatcher

type Dispatcher interface {
	Call(name string, args []byte) ([]byte, error)
	LeaderAddr() string
}

Dispatcher is the seam onto a backing store: run an op by name with binary args and get the encoded result (or an error). *rostam.directStore's dispatcher, *shard.Store, and *cluster.Node all satisfy it — the same interface the TCP server uses.

type Options

type Options struct {
	Authenticator Authenticator
	// Admin, when non-nil, backs the OPT-IN object-storage admin endpoints
	// (POST /v1/admin/backup, GET /v1/admin/backups, POST
	// /v1/collections/{name}/evict, POST /v1/collections/{name}/restore). nil ⇒
	// those routes are still registered but return 412 (object storage not
	// configured) after the admin-scope auth check, so an admin call against an
	// un-tiered server fails loud rather than 404-ing.
	Admin AdminBackend
}

Options configures a Handler.