api

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package api is the OpenArch REST client. The generated code is in package gen (run 'make generate' after a change to api/openapi.json).

Index

Constants

This section is empty.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is wrapped by the errors of calls that got HTTP 404.

Functions

func IsPath

func IsPath(ref string) bool

IsPath reports whether ref is a document path (it starts with "/") rather than an id.

Types

type Blob added in v0.3.1

type Blob struct {
	Filename string `json:"filename"`
	MimeType string `json:"mimeType"`
	Length   int64  `json:"length"`
	Digest   string `json:"digest"`
}

Blob describes the file of a SysFile document (property sysfile_blob). Digest is the SHA-256 of the content, in hex.

type Client

type Client struct {
	Gen *gen.ClientWithResponses
	// contains filtered or unexported fields
}

Client calls the OpenArch API with one set of credentials.

func New

func New(creds auth.Credentials, log *slog.Logger) (*Client, error)

New returns a client. log receives one debug line per request and response, with the Authorization header redacted.

func (*Client) Check

func (c *Client) Check(status int, what string) error

Check maps an HTTP status to a CLI error. 401 and 403 are authentication errors (exit code 6); other non-2xx statuses are remote errors (exit code 5).

func (*Client) CreateDocument

func (c *Client) CreateDocument(ctx context.Context, parent string, body []byte) (Document, error)

CreateDocument creates a document under a parent given by id or path. body is a JSON object.

func (*Client) DeleteDocument

func (c *Client) DeleteDocument(ctx context.Context, id string) error

DeleteDocument deletes a document by id.

func (*Client) Download added in v0.3.1

func (c *Client) Download(ctx context.Context, ref string, w io.Writer) (DownloadResult, error)

Download writes the file of the document ref to w and checks its SHA-256 against the digest stored by OpenArch.

func (*Client) GetDocument

func (c *Client) GetDocument(ctx context.Context, ref string) (Document, error)

GetDocument returns a document by id, or by path when ref starts with "/".

func (*Client) ListChildren added in v0.3.1

func (c *Client) ListChildren(ctx context.Context, ref string, o ListOptions) (QueryResult, error)

ListChildren returns the documents in the folder ref, sorted by name. It reads the database (sync), so a new document shows at once.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) (PingResult, error)

Ping reads the server version and checks the credentials with an authenticated call.

func (*Client) Query

func (c *Client) Query(ctx context.Context, o QueryOptions) (QueryResult, error)

Query runs a query (POST /api/query).

func (*Client) Transport

func (c *Client) Transport(err error, what string) error

Transport turns a request error into a CLI error with exit code 5.

func (*Client) URL

func (c *Client) URL() string

URL returns the server URL.

func (*Client) UploadFile added in v0.3.1

func (c *Client) UploadFile(ctx context.Context, parent, name, title, mimeType string, content io.Reader) (Document, error)

UploadFile creates a SysFile document under parent and attaches content: it creates the document, uploads the content (POST /api/upload), then sets sysfile_blob to the upload. When a later step fails, the new document is deleted again.

type Document

type Document struct {
	Raw json.RawMessage
	// contains filtered or unexported fields
}

Document is a document as returned by OpenArch. It is kept as raw JSON, so that no property is lost, with the fields the CLI shows in text mode decoded.

func (Document) MarshalJSON

func (d Document) MarshalJSON() ([]byte, error)

MarshalJSON writes the document exactly as OpenArch returned it.

func (Document) WriteText

func (d Document) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type DownloadResult added in v0.3.1

type DownloadResult struct {
	Document string `json:"document"`
	Blob
	SHA256 string `json:"sha256"`
}

DownloadResult describes a downloaded file.

type ListOptions added in v0.3.1

type ListOptions struct {
	Limit  int64
	Offset int64
}

ListOptions are the inputs of ListChildren.

type PingResult

type PingResult struct {
	URL           string       `json:"url"`
	User          string       `json:"user"`
	Version       string       `json:"version,omitempty"`
	Authenticated bool         `json:"authenticated"`
	Sources       auth.Sources `json:"sources"`
	Workspace     string       `json:"workspace,omitempty"`
}

PingResult is the outcome of Ping.

func (PingResult) WriteText

func (p PingResult) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type QueryOptions

type QueryOptions struct {
	Query  string
	Syntax string // "" (hxql) or "expr"
	Limit  int64
	Offset int64
	Sort   []string
	// Sync waits until the full-text index has the latest changes.
	Sync bool
	// Total asks the server to count every match.
	Total bool
}

QueryOptions are the inputs of Query.

type QueryResult

type QueryResult struct {
	Raw        json.RawMessage
	Documents  []Document
	Count      int64
	TotalCount int64
	Offset     int64
	Truncated  bool
}

QueryResult is the result of a query, kept as raw JSON with the documents decoded.

func (QueryResult) MarshalJSON

func (r QueryResult) MarshalJSON() ([]byte, error)

MarshalJSON writes the result exactly as OpenArch returned it.

func (QueryResult) WriteText

func (r QueryResult) WriteText(w io.Writer) error

WriteText writes one line per document.

Directories

Path Synopsis
Package gen provides primitives to interact with the openapi HTTP API.
Package gen provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL