api

Documentation

Index

• Variables
• func EnvIsTrue(name string, fallback bool) bool
• func EnvOrExit(name string) string
• func EnvOrFallback(name string, fallback string) string
• func EnvSliceOrEmptySlice(name string) []string
• func GetViewpointByContext(c *gin.Context) (*User, Viewpoint)
• func Setup(prefix string, app *gin.Engine, noRoute ...gin.HandlerFunc)
• type App
• type AuthenticationResourceType
• type Config
  • func (config Config) GetPluginConfig(requestedType reflect.Type) interface{}
• type EmailConfig
  • func (emailConfig EmailConfig) Send(source *email.Email) error
• type FieldSchema
• type FieldViews
• type PluginConfig
• type Query
• type QueryValue
  • func (q QueryValue) Match(s string) bool
• type Resource
• type ResourceType
• type ResourceViews
• type SchemaPrivate
• type SchemaPublic
• type Signup
• type Tab
• type TranslatedString
  • func T(lang string, value string) TranslatedString
  • func (t TranslatedString) T(lang string, value string) TranslatedString
• type User
  • func GetUserByContext(c *gin.Context) *User
  • func GetUserByName(uid string) *User
• type Viewpoint
  • func (ctx Viewpoint) Check(allowedViews []string) bool

Variables

var ErrAuthenticationRequired = errors.New("(401) authentication required")

var ErrCaptchaIsDisabled = errors.New("(410) captcha is disabled")

var ErrEmailAlreadyExists = errors.New("(409) an account with this email address already exists")

var ErrIncorrectPassword = errors.New("(401) incorrect password")

var ErrInvalidConfirmationToken = errors.New("(401) invalid confirmation token")

var ErrInvalidRecoveryToken = errors.New("(401) invalid recovery token")

var ErrMethodNotAllowed = errors.New("(405) method not allowed")

var ErrMissingPermission = errors.New("(403) missing permission")

var ErrRecoveryIsDisabled = errors.New("(403) recovery is disabled")

var ErrResourceDoesntExist = errors.New("(404) resource doesn't exist")

var ErrResourceExists = errors.New("(409) resource exists")

var ErrResourceTypeDoesntExist = errors.New("(404) resource type doesn't exist")

var ErrRouteDoesntExist = errors.New("(404) route doesn't exist")

var ErrSignupsAreDisabled = errors.New("(403) signups are disabled")

var ErrUnparsableRequestBody = errors.New("(400) unparsable request body")

var ErrUserDoesntExist = errors.New("(410) user doesn't exist")

var ErrUsernameAlreadyExists = errors.New("(409) an account with this username already exists")

var ErrUsernameOrPasswordMissing = errors.New("(400) username or password missing")

Functions

func EnvIsTrue

func EnvIsTrue(name string, fallback bool) bool

EnvIsTrue returns the boolean value of an environment variable. If fallback is false, it only returns true for the values "1", "true", "yes" or "y". If fallback is true, it only returns false for the values "0", "false", "no" or "n".

func EnvOrExit

func EnvOrExit(name string) string

EnvOrExit returns the value of an environment variable. If it's unset, the function prints an error message & exits.

func EnvOrFallback

func EnvOrFallback(name string, fallback string) string

EnvOrFallback returns the value of an environment variable. If it's unset, the function returns the fallback value.

func EnvSliceOrEmptySlice

func EnvSliceOrEmptySlice(name string) []string

EnvSliceOrEmptySlice returns a slice from a comma-separated environment variable, or an empty slice if it doesn't exist.

func GetViewpointByContext

func GetViewpointByContext(c *gin.Context) (*User, Viewpoint)

func Setup

func Setup(prefix string, app *gin.Engine, noRoute ...gin.HandlerFunc)

Types

type App

type App struct {
	Name        TranslatedString `json:"name"`
	Description TranslatedString `json:"description"`
	URL         string           `json:"url"`
	Icon        string           `json:"icon"`
	Views       []string         `json:"views"`
}

type AuthenticationResourceType

type AuthenticationResourceType interface {
	ResourceType
	Authenticate(username string, password string) (User, error) // must return the plain user object if the password is an empty string
	Signup(signup Signup, validateOnly bool) map[string]error
	SetPassword(username string, newPassword string) error
}

TODO: document

type Config

type Config struct {
	CanonicalRootURL          string
	ListenAddress             string
	UserResource              string
	RequireEmailConfirmation  bool
	RequireAccept             []string
	RequireAdminConfirmation  bool
	AdminConfirmationGroups   []string
	AdminConfirmationEmails   []string
	AdminConfirmationLanguage string
	Links                     map[string]string
	EnableSignup              bool
	EnableSignupCaptcha       bool
	EnableRecovery            bool
	EmailConfig               EmailConfig
	PluginConfig              []PluginConfig
	Resources                 map[string]ResourceType
	Apps                      []App
	Tabs                      []Tab
}

TODO: document

var ActiveConfig Config

ActiveConfig is the currently used configurations

func (Config) GetPluginConfig

func (config Config) GetPluginConfig(requestedType reflect.Type) interface{}

GetPluginConfig retrieves the configuration for a specific plugin by the configuration's type.

type EmailConfig

type EmailConfig struct {
	Server             string // The server's address including its port (e.g. "smtp.postmarkapp.com:587")
	Username           string // The username used to authenticate against the SMTP server
	Password           string // The password used to authenticate against the SMTP server
	UsePlainTLS        bool   // Force a plain TLS connection instead of opportunistic STARTTLS
	InsecureSkipVerify bool   // Accept any server certificate (insecure, only works with plain TLS)
	FromAddress        string // The sender address for emails
}

EmailConfig for sending email via SMTP.

func (EmailConfig) Send

func (emailConfig EmailConfig) Send(source *email.Email) error

Send an email according to the configuration.

type FieldSchema

type FieldSchema struct {
	Name    string                 `json:"name"`    // The name of the field, as displayed in the frontend. TODO: translation?!
	Type    string                 `json:"type"`    // The type of the field, which has to be supported by the frontend.
	Options map[string]interface{} `json:"options"` // The options of the field that are relevant for the presentation.

	ReadViews  []string `json:"readViews"`
	WriteViews []string `json:"writeViews"`
}

TODO: document

type FieldViews

type FieldViews struct {
	Read   []string // List of views that are sufficient to read a resource of this type.
	Update []string // List of views that are sufficient to update a resource of this type.
}

ResourceViews is a list of allowed views for various request types.

type PluginConfig

type PluginConfig interface {
	SetupPlugin() error
}

TODO: document

type Query

type Query map[string]QueryValue

type QueryValue

type QueryValue struct {
	IsRegex bool
	IsEqual bool
	Value   string
	// contains filtered or unexported fields
}

func (QueryValue) Match

func (q QueryValue) Match(s string) bool

type Resource

type Resource interface {
	ID() string

	Create(id string) error // TODO: document
	Read(id string) error   // Get the resource from the storage backend
	Update(id string) error // Store the resource & populate the ID

	Delete(id string, viewpoint Viewpoint) error // Delete the resource

	FromBody(body map[string]interface{}, viewpoint Viewpoint) map[string]error // Validate & apply the request body of a POST or PUT request
	ToBody(viewpoint Viewpoint) (map[string]interface{}, error)                 // Retrieve a response body for a GET request
}

Resource represents a specific resource (e.g. the user "admin") by its ID.

type ResourceType

type ResourceType interface {
	Setup() error  // Validate the configuration of the resource type
	New() Resource // Create a new resource object
	ListCheck(viewpoint Viewpoint) error
	List(query Query) ([]string, error) // Get a list of resource IDs matching the given query
	Schema() []FieldSchema              // Get the schema for this resource type
}

ResourceType represents a type of resources (e.g. users, groups, books, ...).

type ResourceViews

type ResourceViews struct {
	Create []string // List of views that are sufficient to create a resource of this type.
	List   []string // List of views that are sufficient to list resources of this type.
	Delete []string // List of views that are sufficient to delete a resource of this type.
}

ResourceViews is a list of allowed views for various request types.

type SchemaPrivate

type SchemaPrivate struct {
	SchemaPublic
	UserResource string                   `json:"userResource"`
	Apps         []App                    `json:"apps"`
	Tabs         []Tab                    `json:"tabs"`
	Resources    map[string][]FieldSchema `json:"resources"`
	Viewpoints   []string                 `json:"viewpoints"`
}

type SchemaPublic

type SchemaPublic struct {
	CanonicalRootURL         string            `json:"canonicalRootURL"`
	EnableRecovery           bool              `json:"enableRecovery"`
	EnableSignup             bool              `json:"enableSignup"`
	EnableSignupCaptcha      bool              `json:"enableSignupCaptcha"`
	RequireAccept            []string          `json:"requireAccept"`
	RequireAdminConfirmation bool              `json:"requireAdminConfirmation"`
	Links                    map[string]string `json:"links"`
	RequireEmailConfirmation bool              `json:"requireEmailConfirmation"`
}

type Signup

type Signup struct {
	Username string          `json:"username"`
	Password string          `json:"password"`
	Name     string          `json:"name"`
	Email    string          `json:"email"`
	Accept   map[string]bool `json:"accept"`
	Language string
	Captcha  struct {
		ID       string `json:"id"`
		Response string `json:"response"`
	} `json:"captcha"`
}

type Tab

type Tab struct {
	Name         TranslatedString       `json:"name"`
	Icon         string                 `json:"icon"`
	Type         string                 `json:"type"`
	ResourceType string                 `json:"resourceType"`
	ResourceID   string                 `json:"resourceID"`
	Views        []string               `json:"views"`
	Options      map[string]interface{} `json:"options"`
}

type TranslatedString

type TranslatedString map[string]string

func T

func T(lang string, value string) TranslatedString

func (TranslatedString) T

func (t TranslatedString) T(lang string, value string) TranslatedString

type User

type User struct {
	UID      string   `json:"username"`
	MemberOf []string `json:"memberOf"`
	Name     string   `json:"name"`
	Email    []string `json:"email"`
}

func GetUserByContext

func GetUserByContext(c *gin.Context) *User

func GetUserByName

func GetUserByName(uid string) *User

type Viewpoint

type Viewpoint map[string]struct{}

Viewpoint is the list of visible views during a request.

func (Viewpoint) Check

func (ctx Viewpoint) Check(allowedViews []string) bool