Help us shape the future of Go! Take the 2026 Go Developer Survey

driveapi

package
v0.68.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package driveapi holds the wire types of the Hive Drive server API, shared by the server and its clients so the two cannot drift.

Index

Constants

View Source
const (
	SnippetMatchStart = "\ue000"
	SnippetMatchEnd   = "\ue001"
)

Snippet markers wrap each matched run in SearchHit.Snippet. They are private-use characters, so a client escapes the text and then turns the markers into highlight elements without parsing HTML from the server.

View Source
const ShareExpiryNone = "none"

ShareExpiryNone, as ShareRequest.ExpiresIn, removes a link's expiry.

Variables

This section is empty.

Functions

func DocPath

func DocPath(s drive.Space, path string) string

DocPath is the route of one document. A document path is escaped per segment, so a space, "#", or "?" in a name stays part of the path.

func Host

func Host(server string) (string, error)

Host is the normalized host[:port] of server. It names the stored credential and the upload records, so one server has one spelling.

func SpacePrefix

func SpacePrefix(s drive.Space) string

SpacePrefix is the route prefix of a space, without a trailing slash.

Types

type APIError

type APIError struct {
	Status int
	Body   ErrorBody
}

APIError is a non-2xx response. Body is zero when the server sent no JSON error body, for example from a proxy in front of it.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the drive server API as one token holder.

func NewClient

func NewClient(server string, token func() string) (*Client, error)

NewClient returns a client for server, a URL or host[:port]. token is read on every request, so a rotated credential applies without a new client.

func (*Client) Get

func (c *Client) Get(ctx context.Context, space drive.Space, path string) (Document, []byte, error)

Get returns the document body. The server sends the body alone, so the returned Document holds what the client can know: space, path, kind, size, and the body's sha256.

func (*Client) List

func (c *Client) List(ctx context.Context, space drive.Space) ([]Document, error)

func (*Client) Me

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

func (*Client) Put

func (c *Client) Put(ctx context.Context, space drive.Space, path string, body []byte) (Document, error)

Put stores body at path, replacing any document there.

func (*Client) Share

func (c *Client) Share(ctx context.Context, space drive.Space, path, expiresIn string) (Share, error)

Share creates the document's public link, or returns the existing one. expiresIn is "", "1d", "7d", "30d", or "none". "" leaves an existing link's expiry unchanged and gives a new link none. "none" clears the expiry.

type CreateToken

type CreateToken struct {
	Name      string `json:"name"`
	Scope     string `json:"scope"                tstype:"TokenScope"`
	ExpiresIn string `json:"expires_in,omitempty"`
}

CreateToken.Scope is "read" or "push". ExpiresIn is "", "1d", "7d", "30d", "90d", or "365d"; "" never expires.

type CreatedToken

type CreatedToken struct {
	Secret string `json:"secret"`
	Token  `tstype:",extends"`
}

CreatedToken is the only response that carries the secret.

type Document

type Document struct {
	ID    string `json:"id"`
	Space string `json:"space"`
	Path  string `json:"path"`
	// Title is the frontmatter title, else the first "# " heading, else the
	// file name without its extension.
	Title     string     `json:"title"`
	Kind      drive.Kind `json:"kind"             tstype:"DocumentKind"`
	SHA256    string     `json:"sha256"`
	Size      int64      `json:"size"`
	UpdatedAt time.Time  `json:"updated_at"`
	Shared    *Share     `json:"shared,omitempty"`
}

Document is an element of the JSON arrays that GET /api/v1/{space}, GET /api/v1/recent?limit= (newest first, default 50, at most 200), and GET /api/v1/shared-links (every document with a link, newest first) return.

type ErrorBody

type ErrorBody struct {
	Kind    string            `json:"kind"`
	Message string            `json:"message"`
	Fields  map[string]string `json:"fields,omitempty"`
}

ErrorBody is the JSON shape of every error response. It matches internal/web.ErrorBody, which a platform package may not import.

type Me

type Me struct {
	Email  string `json:"email"`
	Policy string `json:"policy"`
	Quota  Quota  `json:"quota"`
}

type PublicDocument

type PublicDocument struct {
	OwnerEmail string   `json:"owner_email"`
	Document   Document `json:"document"`
	Body       string   `json:"body,omitempty"`
}

PublicDocument is what a share link serves to a reader who is not signed in. Body is set for markdown only; HTML is served from the raw route.

type Quota

type Quota struct {
	Used  int64  `json:"used"`
	Limit *int64 `json:"limit" tstype:"number | null,required"`
}

Quota.Limit is nil for an unlimited policy.

type SearchHit

type SearchHit struct {
	Document Document `json:"document"`
	Snippet  string   `json:"snippet"`
}

SearchHit is one result of GET /api/v1/search. Title matches rank above body matches.

type SearchResults

type SearchResults struct {
	Hits []SearchHit `json:"hits"`
}

type Share

type Share struct {
	URL       string     `json:"url"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	// ExpiresIn is the preset behind ExpiresAt: "1d", "7d", "30d", or "" for
	// no expiry.
	ExpiresIn string `json:"expires_in" tstype:"ShareExpiry"`
}

type ShareRequest

type ShareRequest struct {
	ExpiresIn string `json:"expires_in,omitempty"`
}

ShareRequest.ExpiresIn is "" (keep the link's expiry), "none", "1d", "7d", or "30d".

type SignInStart

type SignInStart struct {
	Email string `json:"email"`
}

type SignInVerify

type SignInVerify struct {
	Email string `json:"email"`
	Code  string `json:"code"`
}

type SpaceSummary

type SpaceSummary struct {
	Space     string          `json:"space"`
	Kind      drive.SpaceKind `json:"kind"      tstype:"'repository' | 'workspace' | 'shared'"`
	Documents int             `json:"documents"`
	Bytes     int64           `json:"bytes"`
}

type Token

type Token struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	Scope      string     `json:"scope"                  tstype:"TokenScope"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
}

Jump to

Keyboard shortcuts

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