Documentation
¶
Overview ¶
Package beacons is a thin client for the Truestamp Beacons JSON:API surface (GET /api/json/beacons, /beacons/latest, /beacons/:id, /beacons/by-hash/:hash). A Beacon is a compact "proof of life" projection of a finalized block: {id, hash, timestamp, previous_hash}. The server side is documented in truestamp-v2/kb/api/beacon-api.md.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrForbidden = jsonapi.ErrForbidden ErrNotFound = jsonapi.ErrNotFound ErrBadRequest = jsonapi.ErrBadRequest ErrRateLimited = jsonapi.ErrRateLimited ErrServer = jsonapi.ErrServer )
Functions ¶
func ValidateHash ¶
ValidateHash returns nil iff s is exactly 64 lowercase hex characters.
func ValidateUUIDv7 ¶
ValidateUUIDv7 returns nil iff s parses as a UUID whose version is 7.
Types ¶
type APIError ¶
The transport, the class sentinels and APIError live in internal/jsonapi; these aliases keep this client's surface stable for the commands that errors.Is its classes.
type Beacon ¶
type Beacon struct {
ID string `json:"id"` // UUIDv7
Hash string `json:"hash"` // 64 lowercase hex
Timestamp string `json:"timestamp"` // ISO 8601 UTC
PreviousHash string `json:"previous_hash"` // 64 lowercase hex
}
Beacon is the JSON shape returned by every beacon endpoint. All four fields are always present on success; a missing field is treated as a parse error rather than recovered from.
type Config ¶
The transport, the class sentinels and APIError live in internal/jsonapi; these aliases keep this client's surface stable for the commands that errors.Is its classes.
type ListOptions ¶ added in v0.14.0
type ListOptions struct {
Limit int
After string // continue forward from a Page.NextCursor
Before string // continue backward from a Page.PrevCursor
OldestFirst bool // walk from the genesis beacon instead of the newest
Count bool
}
ListOptions configures a list request; the paging fields are the ones every keyset-paged list shares (jsonapi.SetPageQuery).
type Page ¶ added in v0.14.0
type Page struct {
Beacons []Beacon
NextCursor string
PrevCursor string
Total int
Limit int // the page size the server actually used
}
Page is one page of beacons plus the cursors for its neighbours and, when asked for, the server's total.
func List ¶
List fetches one page of beacons, newest first unless asked otherwise.
GET /beacons is a JSON:API index over a keyset-paginated read, the same contract as /blocks: page[limit], page[after], page[before], page[count] and sort=id|-id, answered as a resource document with links.next/prev and meta.page.total. Like every collection it clamps page[limit] to its max_page_size (250) and reports the size used in meta.page.limit; the floor is cmd/limits.go's.
Source Files