Documentation
¶
Overview ¶
Package sdk defines the contract between the Gophenberg core and its plugins. It is the only Gophenberg package a plugin may import.
Index ¶
- Variables
- func Misuse(err error) error
- func WithSession(ctx context.Context, session Session) context.Context
- type AccountReader
- type Call
- type Command
- type CommandProvider
- type ContentReader
- type DB
- type Deps
- type Engine
- type Env
- func (e Env) Count(name string, fallback int) (int, error)
- func (e Env) Counts(name string, fallback []int) ([]int, error)
- func (e Env) Duration(name string, fallback time.Duration) (time.Duration, error)
- func (e Env) Flag(name string, fallback bool) (bool, error)
- func (e Env) Key(name string) string
- func (e Env) Required(name string) (string, error)
- func (e Env) Value(name string) string
- func (e Env) Within(more string) Env
- type FieldDeclaration
- type GroupDeclaration
- type HostOnly
- type ID
- type Item
- type Migrator
- type Person
- type Plugin
- type PublicPathProvider
- type Querier
- type RoleDeclaration
- type RoleProvider
- type RouteProvider
- type Row
- type Rows
- type Rule
- type Session
- type Tx
- type TypeDeclaration
- type TypeDeclarer
- type TypeRegistrar
Constants ¶
This section is empty.
Variables ¶
var ErrMisused = errors.New("misused command line")
ErrMisused marks an error as a misused command line, which exits with code 2.
Functions ¶
Types ¶
type AccountReader ¶ added in v0.5.0
type AccountReader interface {
People(ctx context.Context, ids []ID, avatarSize int) (map[ID]Person, error)
// contains filtered or unexported methods
}
AccountReader reads many accounts by id in one call for plugins, which only the site implements.
type Call ¶
type Call struct {
Args []string
Flags map[string]string
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
JSON bool
Apply bool
Actor string
}
Call is what a plugin command receives when it runs.
type Command ¶
type Command struct {
Name string
Summary string
Args []string
Flags func(fs *flag.FlagSet)
Needs []string
Writes bool
JSON bool
Capability string
Run func(ctx context.Context, call Call) error
}
Command is one command a plugin offers under its id.
type CommandProvider ¶
type CommandProvider interface {
Commands() []Command
}
CommandProvider is implemented by plugins that offer commands under their id.
type ContentReader ¶
type ContentReader interface {
ListPublished(ctx context.Context, contentType string, limit int) ([]Item, error)
}
ContentReader gives plugins read access to published content.
type DB ¶ added in v0.2.0
type DB interface {
Querier
Engine() Engine
Begin(ctx context.Context) (Tx, error)
// contains filtered or unexported methods
}
DB is a plugin's capped share of the site database, which only the site implements.
type Deps ¶
type Deps struct {
DatabaseURL string
DB DB
Content ContentReader
Accounts AccountReader
Getenv func(string) string
Env Env
}
Deps carries the host-provided dependencies a plugin's Register function receives at registration.
type Env ¶
Env reads the settings under the program prefix.
func (Env) Count ¶
Count returns the setting as a whole number above zero, the fallback when it is empty.
func (Env) Counts ¶
Counts returns the setting as rising whole numbers above zero split by commas, the fallback when it is empty.
func (Env) Duration ¶
Duration returns the setting as a duration above zero, the fallback when it is empty.
type FieldDeclaration ¶
type FieldDeclaration struct {
Key string
Label string
Kind string
RelatesTo string
Many bool
Required bool
Listed bool
Conditions [][]Rule
Settings map[string]any
Fields []FieldDeclaration
}
FieldDeclaration is a field as a plugin declares it, holding the fields a container declares inside.
type GroupDeclaration ¶
type GroupDeclaration struct {
Key string
Title string
Location [][]Rule
Fields []FieldDeclaration
}
GroupDeclaration is a field group as a plugin declares it, with the fields it holds.
type HostOnly ¶ added in v0.2.0
type HostOnly struct{}
HostOnly seals an SDK interface to the site, which embeds it in the type it lends.
type ID ¶
type ID [16]byte
ID identifies a content item or an account, sixteen bytes the host assigns.
func (ID) MarshalText ¶
MarshalText returns the id in its canonical form, so JSON carries it as text.
func (ID) String ¶
String returns the id in its canonical form, 36 lowercase characters with hyphens.
func (*ID) UnmarshalText ¶
UnmarshalText reads the id from its canonical form in either case, leaving it unchanged on a refusal.
type Item ¶
type Item struct {
ID ID
Type string
Path string
Slug string
Title string
Excerpt string
Content string
Fields map[string]any
PublishedAt time.Time
UpdatedAt time.Time
}
Item is a published content item as plugins see it: the Content field holds sanitized block HTML, and Fields holds the values the content API serves, decoded the way encoding/json decodes them.
type Migrator ¶
Migrator is implemented by plugins that own database schema, which the host migrates before starting any plugin.
type Person ¶ added in v0.5.0
Person is an account as plugins see it: its public face and never its email address.
type Plugin ¶
type Plugin interface {
ID() string
Start(ctx context.Context) error
Stop(ctx context.Context) error
}
Plugin is an independently addable unit of functionality with a managed lifecycle.
type PublicPathProvider ¶
type PublicPathProvider interface {
PublicPaths() []string
}
PublicPathProvider is implemented by plugins declaring session-exempt public paths.
type Querier ¶ added in v0.2.0
type Querier interface {
Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
Query(ctx context.Context, query string, args ...any) (Rows, error)
QueryRow(ctx context.Context, query string, args ...any) Row
}
Querier runs statements written with $1, $2 placeholders, each within the site's statement timeout.
type RoleDeclaration ¶ added in v0.4.0
RoleDeclaration is one role a plugin declares, or capabilities it adds to a role the host knows.
type RoleProvider ¶ added in v0.4.0
type RoleProvider interface {
Roles() []RoleDeclaration
}
RoleProvider is implemented by plugins declaring roles or widening the ones the host knows.
type RouteProvider ¶
RouteProvider is implemented by plugins that expose HTTP endpoints under their own namespace.
type Rows ¶ added in v0.2.0
type Rows interface {
Next() bool
NextResultSet() bool
Scan(dest ...any) error
Close() error
Err() error
}
Rows is the answer of a query, read one row at a time and closed when done.
type Session ¶
type Session struct {
ID ID
Email string
Name string
Role string
// contains filtered or unexported fields
}
Session is the account a request is made by, as a plugin reads it.
func NewSession ¶
NewSession returns the session a host files for a request.
func SessionFrom ¶
SessionFrom returns the session a request was made by, reporting whether one was filed.
type Tx ¶ added in v0.2.0
Tx is a transaction on a plugin's share of the site database, ending at the site's transaction timeout.
type TypeDeclaration ¶
type TypeDeclaration struct {
Key string
SingularLabel string
PluralLabel string
Description string
RouteWord string
Hierarchical bool
Revisions bool
RevisionCap int
PageKind string
}
TypeDeclaration is a content type as a plugin declares it.
type TypeDeclarer ¶
type TypeDeclarer interface {
DeclareTypes(ctx context.Context, types TypeRegistrar) error
}
TypeDeclarer is implemented by plugins that declare content types, groups or fields.
type TypeRegistrar ¶
type TypeRegistrar interface {
DeclareType(ctx context.Context, declared TypeDeclaration) error
DeclareGroup(ctx context.Context, declared GroupDeclaration) error
DeclareField(ctx context.Context, groupKey string, declared FieldDeclaration) error
}
TypeRegistrar takes the definitions a plugin declares, once per boot.