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
- func DocPath(s drive.Space, path string) string
- func Host(server string) (string, error)
- func SpacePrefix(s drive.Space) string
- type APIError
- type Client
- func (c *Client) Get(ctx context.Context, space drive.Space, path string) (Document, []byte, error)
- func (c *Client) List(ctx context.Context, space drive.Space) ([]Document, error)
- func (c *Client) Me(ctx context.Context) (Me, error)
- func (c *Client) Put(ctx context.Context, space drive.Space, path string, body []byte) (Document, error)
- func (c *Client) Share(ctx context.Context, space drive.Space, path, expiresIn string) (Share, error)
- type CreateToken
- type CreatedToken
- type Document
- type ErrorBody
- type Me
- type PublicDocument
- type Quota
- type SearchHit
- type SearchResults
- type Share
- type ShareRequest
- type SignInStart
- type SignInVerify
- type SpaceSummary
- type Token
Constants ¶
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.
ShareExpiryNone, as ShareRequest.ExpiresIn, removes a link's expiry.
Variables ¶
This section is empty.
Functions ¶
func DocPath ¶
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 ¶
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 ¶
SpacePrefix is the route prefix of a space, without a trailing slash.
Types ¶
type APIError ¶
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.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the drive server API as one token holder.
func NewClient ¶
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 ¶
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) 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 ¶
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"`
}
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 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 ¶
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 {
// no expiry.
ExpiresIn string `json:"expires_in" tstype:"ShareExpiry"`
}
type ShareRequest ¶
type ShareRequest struct {
}
ShareRequest.ExpiresIn is "" (keep the link's expiry), "none", "1d", "7d", or "30d".
type SignInStart ¶
type SignInStart struct {
Email string `json:"email"`
}