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

api

package
v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: GPL-3.0 Imports: 34 Imported by: 0

Documentation

Overview

Package api serves the client and admin surfaces through policy-classed registrations, plus a fixed loopback health endpoint.

Index

Constants

View Source
const (
	DefaultReadsPerMinute    = 600
	DefaultSearchesPerMinute = 60
)

Variables

View Source
var (
	ErrAlreadyPaired     error = &codedError{status: http.StatusConflict, code: "already_paired"}
	ErrAlreadyConnected  error = &codedError{status: http.StatusConflict, code: "already_connected"}
	ErrNotPaired         error = &codedError{status: http.StatusConflict, code: "not_paired"}
	ErrOwnerPhoneMissing error = &codedError{status: http.StatusConflict, code: "owner_phone_missing"}
	ErrOwnerMismatch     error = &codedError{status: http.StatusConflict, code: "owner_mismatch"}
	ErrRateLimited       error = &codedError{status: http.StatusTooManyRequests, code: codeRateLimited}
	ErrPairFailed        error = &codedError{status: http.StatusBadGateway, code: "pair_failed"}
	ErrEngineUnavailable error = &codedError{status: http.StatusServiceUnavailable, code: "engine_unavailable"}
	ErrBackfillNoAnchor  error = &codedError{status: http.StatusUnprocessableEntity, code: codeBackfillNoAnchor}
)
View Source
var (
	ErrMediaUnavailable error = errMediaUnavailable
	ErrMediaExpired     error = errMediaExpired
	ErrMediaTooLarge    error = errMediaTooLarge
	ErrMediaUnsupported error = errMediaUnsupported
	ErrMediaFailed      error = errMediaFailed
)
View Source
var (
	ErrNotFound           error = errNotFound
	ErrBusy               error = errBusy
	ErrKeyReused          error = &codedError{status: http.StatusUnprocessableEntity, code: codeKeyReused}
	ErrFirstContact       error = &codedError{status: http.StatusForbidden, code: codeFirstContact}
	ErrNotConnected       error = &codedError{status: http.StatusServiceUnavailable, code: codeNotConnected, retryAfter: notConnected}
	ErrSendRejected       error = &codedError{status: http.StatusBadGateway, code: codeSendRejected}
	ErrSendOutcomeUnknown error = &codedError{status: http.StatusGatewayTimeout, code: codeSendOutcomeUnknown}
)
View Source
var (
	ErrClientNotFound error = &codedError{status: http.StatusNotFound, code: codeNotFound}
)

Functions

func BackfillQuota added in v1.0.0

func BackfillQuota(wait time.Duration) error

func Busy added in v1.2.0

func Busy(wait time.Duration) error

func InProgress added in v1.0.0

func InProgress(wait time.Duration) error

func NewAdminHandler

func NewAdminHandler(d AdminDeps) http.Handler

func NewClientHandler

func NewClientHandler(d ClientDeps) http.Handler

func NewHealthHandler

func NewHealthHandler(ready func() bool) http.Handler

func RateLimited added in v1.0.0

func RateLimited(wait time.Duration) error

func WellFormedKey added in v1.0.0

func WellFormedKey(key string) bool

Types

type AdminDeps

type AdminDeps struct {
	Credential policy.AdminCredential
	Metrics    *metrics.Registry
	Service    AdminService
	Events     AdminEvents
	Now        func() time.Time
}

type AdminEvents added in v0.2.0

type AdminEvents interface {
	AdminMutation(action, outcome string)
	AdminAuthFailure()
}

type AdminService added in v0.2.0

type AdminService interface {
	Status(ctx context.Context) (AdminStatus, error)
	Pair(ctx context.Context) (code string, err error)
	Reconnect(ctx context.Context) error
	Backfill(g policy.AdminGrant, ctx context.Context, chat policy.CanonicalChat, count int, anchor BackfillAnchor) (requestID string, err error)
	PauseMedia(paused bool)
	ClientService
}

type AdminStatus added in v0.2.0

type AdminStatus struct {
	State            string
	Reason           string
	Paired           bool
	Chats            int64
	Messages         int64
	BlobsPending     int64
	BlobsQuarantined int64
	InboxBacklog     int64
	InboxQuarantined int64
	BackfillsToday   int64
	MediaRefsLive    int64
	MediaRefsExpired int64
	RevokeTombstones int64
	Downloads        bool
	MediaPaused      bool
	Clients          ClientCounts
	LastIngest       time.Time
	Version          string
}

type Auditor added in v0.3.0

type Auditor interface {
	Record(ctx context.Context, e ReadEvent) error
}

type Authenticator

type Authenticator interface {
	Authenticate(ctx context.Context, token string) (*policy.Client, bool, error)
}

type BackfillAnchor added in v1.3.0

type BackfillAnchor uint8
const (
	BackfillOldest BackfillAnchor = iota
	BackfillNewest
)

type ChatEntry added in v0.3.0

type ChatEntry struct {
	Chat policy.CanonicalChat
	Ref  string
	Name string
}

type ClientChatView added in v0.3.0

type ClientChatView struct {
	Chat  policy.CanonicalChat
	Known bool
	Name  string
}

type ClientCounts added in v0.3.0

type ClientCounts struct {
	Active           int64
	Expired          int64
	Revoked          int64
	AllChatsActive   int64
	MediaWriteActive int64
}

type ClientDeps

type ClientDeps struct {
	Authenticator Authenticator
	Metrics       *metrics.Registry
	Now           func() time.Time
	Archive       ReadArchive
	Audit         Auditor
	Session       func() string
	Cursors       *cursor.Sealer
	Refs          *cursor.Sealer
	Limits        ReadLimits
	Sender        SendService
	SendRejected  func(reason string)
	AuditFailed   func(action string, err error)
	Media         *MediaDeps
}

type ClientService added in v0.3.0

type ClientService interface {
	CreateClient(ctx context.Context, spec policy.ClientSpec) (view ClientView, credential string, err error)
	Clients(ctx context.Context) ([]ClientView, error)
	Client(ctx context.Context, id string) (ClientView, error)
	RevokeClient(ctx context.Context, id string) (ClientView, error)
	Chats(ctx context.Context, match string, limit int) (chats []ChatEntry, truncated bool, err error)
}

type ClientView added in v0.3.0

type ClientView struct {
	ID                string
	Name              string
	State             string
	CreatedAt         time.Time
	ExpiresAt         time.Time
	RevokedAt         time.Time
	AllChats          bool
	AllowFirstContact bool
	AllowMedia        bool
	ReadCount         int64
	WriteCount        int64
	Read              []ClientChatView
	Write             []ClientChatView
}

type MediaDeps added in v1.2.0

type MediaDeps struct {
	Service            MediaService
	MaxBytes           int64
	PerMinute          int
	GlobalPerHour      int
	GlobalBytesPerHour int64
	Root               context.Context
	ClientLive         func(ctx context.Context, client string) (bool, error)
	Stopped            func()
	Pause              *MediaPause
	// contains filtered or unexported fields
}

type MediaFetch added in v1.2.0

type MediaFetch struct {
	Chat     policy.CanonicalChat
	ID       string
	Sender   policy.CanonicalChat
	Kind     string
	Variant  string
	Declared int64
}

type MediaPause added in v1.2.0

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

func (*MediaPause) Paused added in v1.2.0

func (p *MediaPause) Paused() bool

func (*MediaPause) Set added in v1.2.0

func (p *MediaPause) Set(paused bool)

type MediaService added in v1.2.0

type MediaService interface {
	Precheck(declared int64) error
	Fetch(ctx context.Context, ref scoped.SealedRef, req MediaFetch) (MediaSpool, error)
}

type MediaSpool added in v1.2.0

type MediaSpool interface {
	Size() int64
	Fetched() int64
	ReadAt(p []byte, off int64) (int, error)
	Erase()
	ServedType() string
	Format() string
	Normalised() bool
	InMemory() bool
}

type ReadEvent added in v0.3.0

type ReadEvent struct {
	At      time.Time
	Client  string
	Action  string
	Chat    policy.CanonicalChat
	OK      bool
	Reason  string
	Peer    string
	Message cursor.Ref
	Bytes   int64
}

type ReadLimits added in v0.3.0

type ReadLimits struct {
	ReadsPerMinute    int
	SearchesPerMinute int
}

type Request

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

func (*Request) DecodeJSON added in v0.2.0

func (r *Request) DecodeJSON(dst any) error

type SendReply added in v1.0.0

type SendReply struct {
	ID     string
	Sender policy.CanonicalChat
	Seq    int64
	Text   string
}

type SendRequest added in v1.0.0

type SendRequest struct {
	Key     string
	Chat    policy.CanonicalChat
	ChatRef string
	Text    string
	Reply   *SendReply
}

type SendService added in v1.0.0

type SendService interface {
	Send(g policy.WriteGrant, ctx context.Context, req SendRequest) (Sent, error)
}

type Sent added in v1.0.0

type Sent struct {
	Chat     policy.CanonicalChat
	ID       string
	Sender   policy.CanonicalChat
	Replayed bool
}

Sent reports a replay on a stored failure as well, beside the error.

Directories

Path Synopsis
Package dto declares every response body the API can send, so nothing else can reach a caller.
Package dto declares every response body the API can send, so nothing else can reach a caller.

Jump to

Keyboard shortcuts

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