sdk

package module
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrMisused = errors.New("misused command line")

ErrMisused marks an error as a misused command line, which exits with code 2.

Functions

func Misuse

func Misuse(err error) error

Misuse marks err as a misused command line, which exits with code 2.

func WithSession

func WithSession(ctx context.Context, session Session) context.Context

WithSession returns a context carrying the session, which only the host fills.

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.

func (Call) Encode

func (c Call) Encode(v any) error

Encode writes v to Stdout as one indented JSON document.

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 Engine added in v0.2.0

type Engine string

Engine names the database engine a site runs on.

const (
	// Postgres is the PostgreSQL engine.
	Postgres Engine = "postgres"
	// SQLite is the SQLite engine.
	SQLite Engine = "sqlite"
)

type Env

type Env struct {
	Prefix string
	Getenv func(string) string
}

Env reads the settings under the program prefix.

func (Env) Count

func (e Env) Count(name string, fallback int) (int, error)

Count returns the setting as a whole number above zero, the fallback when it is empty.

func (Env) Counts

func (e Env) Counts(name string, fallback []int) ([]int, error)

Counts returns the setting as rising whole numbers above zero split by commas, the fallback when it is empty.

func (Env) Duration

func (e Env) Duration(name string, fallback time.Duration) (time.Duration, error)

Duration returns the setting as a duration above zero, the fallback when it is empty.

func (Env) Flag

func (e Env) Flag(name string, fallback bool) (bool, error)

Flag returns the setting as true or false, the fallback when it is empty.

func (Env) Key

func (e Env) Key(name string) string

Key returns the full name of the setting called name.

func (Env) Required

func (e Env) Required(name string) (string, error)

Required returns the setting's value, an error naming it when it is empty.

func (Env) Value

func (e Env) Value(name string) string

Value returns the setting's value with surrounding spaces trimmed, empty when it is unset.

func (Env) Within

func (e Env) Within(more string) Env

Within returns the settings under the prefix followed by more.

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

func (id ID) MarshalText() ([]byte, error)

MarshalText returns the id in its canonical form, so JSON carries it as text.

func (ID) String

func (id ID) String() string

String returns the id in its canonical form, 36 lowercase characters with hyphens.

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(text []byte) error

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

type Migrator interface {
	Migrate(ctx context.Context) error
}

Migrator is implemented by plugins that own database schema, which the host migrates before starting any plugin.

type Person added in v0.5.0

type Person struct {
	ID       ID
	Name     string
	Role     string
	Avatar   string
	Disabled bool
}

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

type RoleDeclaration struct {
	Name         string
	Capabilities []string
}

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

type RouteProvider interface {
	Routes() http.Handler
}

RouteProvider is implemented by plugins that expose HTTP endpoints under their own namespace.

type Row added in v0.2.0

type Row interface {
	Scan(dest ...any) error
	Err() error
}

Row is the answer of a query that returns at most one row.

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 Rule

type Rule struct {
	Source   string
	Operator string
	Value    string
}

Rule is one condition a field group's location reads.

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

func NewSession(id ID, email, name, role string, capabilities []string) Session

NewSession returns the session a host files for a request.

func SessionFrom

func SessionFrom(ctx context.Context) (Session, bool)

SessionFrom returns the session a request was made by, reporting whether one was filed.

func (Session) Can

func (s Session) Can(capability string) bool

Can reports whether the session holds the named capability.

type Tx added in v0.2.0

type Tx interface {
	Querier
	Commit() error
	Rollback() error
}

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.

Jump to

Keyboard shortcuts

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