component

package
v0.0.0-...-dae269f Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2023 License: AGPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package component holds the main abstraction for components.

Package stack implements a docker compose stack

Index

Constants

This section is empty.

Variables

This section is empty.

Functions 

func MenuItemSort(a, b MenuItem) bool

Types

type AccessDeniedError 

type AccessDeniedError string

func (AccessDeniedError) Error 

func (aed AccessDeniedError) Error() string

type Backupable 

type Backupable interface {
	Component

	// BackupName returns a new name to be used as an argument for path.
	BackupName() string

	// Backup backs up this component into the destination path path
	Backup(context *StagingContext) error
}

Backupable represents a component with a Backup method

type Base 

type Base struct {
	Still // the underlying still of the distillery
	// contains filtered or unexported fields
}

Base is embedded into every Component

func (Base) ID 

func (cb Base) ID() string

func (Base) Name 

func (cb Base) Name() string

type CheckError 

type CheckError struct {
	Scope Scope
	Err   error
}

func (CheckError) Error 

func (ce CheckError) Error() string

func (CheckError) Unwrap 

func (ce CheckError) Unwrap() error

type Component 

type Component interface {
	// Name returns the name of this component
	// Name should be implemented by the [ComponentBase] struct.
	Name() string

	// ID returns a unique id of this component
	// ID should be implemented by the [ComponentBase] struct.
	ID() string
	// contains filtered or unexported methods
}

Components represents a logical subsystem of the distillery. A Component should be implemented as a pointer to a struct. Every component must embed Base and should be initialized using Init inside a [lifetime.Lifetime].

By convention these are defined within their corresponding subpackage. This subpackage also contains all required resources.

func Init 

func Init(component Component, core Still) Component

Init initialzes a new componeont Component with the provided still. Init is only initended to be used within a lifetime.Lifetime[Component,Still].

type Cronable 

type Cronable interface {
	Component

	// Name of the cron task being performed
	TaskName() string

	// Cron is called to run this cron task
	Cron(ctx context.Context) error
}

Cronable is a component that implements a cron method

type DistilleryFetcher 

type DistilleryFetcher interface {
	Component

	// Fetch fetches information from this component and writes it into target.
	// Distinct DistilleryFetchers must write into distinct fields.
	Fetch(flags FetcherFlags, target *status.Distillery) error
}

type FetcherFlags 

type FetcherFlags struct {
	Context context.Context
}

FetcherFlags describes options for a DistilleryFetcher

type HostPort 

type HostPort struct {
	Host string
	Port uint32
}

func (HostPort) String 

func (hp HostPort) String() string

type Installable 

type Installable interface {
	Component

	// Path returns the path this component is installed at.
	// By convention it is /var/www/deploy/internal/core/${Name()}
	Path() string

	// Stack can be used to gain access to the "docker compose" stack.
	//
	// This should internally call [ComponentBase.MakeStack]
	Stack() StackWithResources

	// Context returns a new InstallationContext to be used during installation from the command line.
	// Typically this should just pass through the parent, but might perform other tasks.
	Context(parent InstallationContext) InstallationContext
}

Installable implements an installable component.

type InstallationContext 

type InstallationContext map[string]string

InstallationContext is a context to install data in 

type MenuItem struct {
	Title  string
	Path   template.URL
	Active bool

	Priority MenuPriority
	// contains filtered or unexported fields
}

func DummyMenuItem 

func DummyMenuItem() MenuItem

DummyMenuItem creates a new Dummy Menu Item to be replaced 

func (mi MenuItem) ReplaceWith(new MenuItem, items []MenuItem) bool

ReplaceWith replaces this MenuItem with a different MenuItem. This method returns true if an appropriate DummyMenuItem exists. 

type MenuPriority int
const (
	MenuHome MenuPriority = iota
	MenuNews
	MenuResolver
	MenuUser
	MenuAdmin
	MenuAuth
)

Menu* indicates priorities of the menu 

const (
	SmallButton MenuPriority = -1
)
type Menuable interface {
	Component

	Menu(r *http.Request) []MenuItem
}

Menuable is a component that provides a menu

type Provisionable 

type Provisionable interface {
	Component

	// Provision provisions resources specific to the provided instance.
	// Domain holds the full (unique) domain name of the given instance.
	Provision(ctx context.Context, instance models.Instance, domain string) error

	// Purge purges resources specific to the provided instance.
	// Domain holds the full (unique) domain name of the given instance.
	Purge(ctx context.Context, instance models.Instance, domain string) error
}

Provisionable is a component that can be provisioned

type RouteContext 

type RouteContext struct {
	DefaultDomain bool
}

type Routeable 

type Routeable interface {
	Component

	// Routes returns information about the routes to be handled by this Routeable
	Routes() Routes

	// HandleRoute returns the handler for the requested path.
	// Context is cancelled once the handler should be closed.
	HandleRoute(ctx context.Context, path string) (http.Handler, error)
}

Routeable is a component that is servable

type Routes 

type Routes struct {
	// Prefix is the prefix this pattern handles
	Prefix string

	// MatchAllDomains indicates that all domains, even the non-default domain, should be matched
	MatchAllDomains bool

	// Internal indicates that this route should only answer on the internal server.
	// Internal implies MatchAllDomains.
	Internal bool

	// MenuTitle and MenuPriority return the priority and title of this menu item
	MenuTitle    string
	MenuPriority MenuPriority

	// Exact indicates that only the exact prefix, as opposed to any sub-paths, are matched.
	// Trailing '/'s are automatically trimmed, even with an exact match.
	Exact bool

	// Aliases are the additional prefixes this route handles.
	Aliases []string

	// CSRF indicates if this route should be protected by CSRF.
	// CSRF protection is applied prior to any custom decorator being called.
	CSRF bool

	// Decorators is a function applied to the handler returned by HandleRoute.
	// When nil, it is not applied.
	Decorator func(http.Handler) http.Handler
}

Routes represents information about a single Routeable

func (Routes) Decorate 

func (routes Routes) Decorate(handler http.Handler, csrf func(http.Handler) http.Handler) http.Handler

Decorate decorates the provided handler with the options specified in this handler.

func (Routes) Predicate 

func (routes Routes) Predicate(context func(*http.Request) RouteContext) mux.Predicate

Predicate returns the predicate corresponding to the given route

type RunFlags 

type RunFlags struct {
	AutoRemove bool
	Detach     bool
}

type Scope 

type Scope string

Scope represents a single permit by a session to perform some action. Scopes consist of two parts: A general name and a specific object. Scopes are checked by ScopeCheckers.

type ScopeInfo 

type ScopeInfo struct {
	Scope

	// Description is a human readable description of the scope
	Description string

	// error returned to a user when the permission is denied.
	// defaults to "missing scope {{ name }}"
	DeniedMessage string

	// TakesParam indicates if the scope accepts a parameter
	TakesParam bool
}

func (ScopeInfo) CheckError 

func (scope ScopeInfo) CheckError(err error) error

CheckError returns a CheckError with the given underlying error.

func (ScopeInfo) DeniedError 

func (scope ScopeInfo) DeniedError() error

DeniedError returns an AccessDeniedError that indivates the access is denied.

type ScopeProvider 

type ScopeProvider interface {
	Component

	// Scopes returns information about the scope
	Scope() ScopeInfo

	// Check checks if the given session has access to the given scope.
	HasScope(param string, r *http.Request) (bool, error)
}

ScopeProvider is a component that can check a specific scope

type SessionInfo 

type SessionInfo struct {
	// User is the current user associated with the session.
	User *models.User

	// Token indicates if the user was authenticated with a Token
	Token bool
}

SessionInfo provides information about the current session.

func (SessionInfo) Anonymous 

func (si SessionInfo) Anonymous() bool

Anonymous reports if this Session is associated with a user account

func (SessionInfo) MarshalJSON 

func (si SessionInfo) MarshalJSON() ([]byte, error)

func (SessionInfo) Username 

func (si SessionInfo) Username() string

Username reports the username associated with this session

type Snapshotable 

type Snapshotable interface {
	Component

	// SnapshotNeedsRunning returns if this Snapshotable requires a running instance.
	SnapshotNeedsRunning() bool

	// SnapshotName returns a new name to be used as an argument for path.
	SnapshotName() string

	// Snapshot snapshots a part of the instance
	Snapshot(wisski models.Instance, context *StagingContext) error
}

Snapshotable represents a component with a Snapshot method.

type Stack 

type Stack struct {
	Dir string // Directory this Stack is located in

	DockerExecutable string // Path to the native docker executable to use
}

Stack represents a 'docker compose' stack living in a specific directory

NOTE(twiesing): In the current implementation this requires a 'docker' executable on the system. This executable must be capable of the 'docker compose' command. In the future the idea is to replace this with a native docker compose client.

func (Stack) Down 

func (ds Stack) Down(ctx context.Context, progress io.Writer) error

Down stops and removes all containers in this Stack. It is equivalent to 'docker compose down -v' on the shell.

func (Stack) DownAll 

func (ds Stack) DownAll(ctx context.Context, progress io.Writer) error

DownAll stops and removes all containers in this Stack, and those not defined in the compose file. It is equivalent to 'docker compose down -v --remove-orphans' on the shell.

func (Stack) Exec 

func (ds Stack) Exec(ctx context.Context, io stream.IOStream, service, executable string, args ...string) func() int

Exec executes an executable in the provided running service. It is equivalent to 'docker compose exec $service $executable $args...'.

It returns the exit code of the process.

func (Stack) Kill 

func (ds Stack) Kill(ctx context.Context, progress io.Writer, service string, signal os.Signal) error

func (Stack) Restart 

func (ds Stack) Restart(ctx context.Context, progress io.Writer) error

Restart restarts all containers in this Stack. It is equivalent to 'docker compose restart' on the shell.

func (Stack) Run 

func (ds Stack) Run(ctx context.Context, io stream.IOStream, flags RunFlags, service, command string, args ...string) (int, error)

Run runs a command in a running container with the given executable. It is equivalent to 'docker compose run [--rm] $service $executable $args...'.

It returns the exit code of the process.

func (Stack) Up 

func (ds Stack) Up(ctx context.Context, progress io.Writer) error

Up creates and starts the containers in this Stack. It is equivalent to 'docker compose up --force-recreate --remove-orphans --detach' on the shell.

func (Stack) Update 

func (ds Stack) Update(ctx context.Context, progress io.Writer, start bool) error

Update pulls, builds, and then optionally starts this stack. This does not have a direct 'docker compose' shell equivalent.

See also Up.

type StackWithResources 

type StackWithResources struct {
	Stack

	// Installable enabled installing several resources from a (potentially embedded) filesystem.
	//
	// The Resources holds these, with appropriate resources specified below.
	// These all refer to paths within the Resource filesystem.
	Resources fs.FS

	ContextPath string // the 'docker compose' stack context. May or may not contain 'docker-compose.yml'

	ComposerYML func(*yaml.Node) (*yaml.Node, error) // update 'docker-compose.yml', if no 'docker-compose.yml' exists, the passed node is nil.

	EnvContext map[string]string // context when instantiating the '.env' template

	CopyContextFiles []string // Files to copy from the installation context

	MakeDirsPerm fs.FileMode // permission for dirctories, defaults to [environment.DefaultDirCreate]
	MakeDirs     []string    // directories to ensure that exist

	TouchFilesPerm fs.FileMode // permission for new files to touch, defaults to [environment.DefaultFileCreate]
	TouchFiles     []string    // Files to 'touch', i.e. ensure that exist; guaranteed to be run after MakeDirs
}

StackWithResources represents a Stack that can be automatically installed from a set of resources. See the [Install] method.

func MakeStack 

func MakeStack(component Installable, stack StackWithResources) StackWithResources

MakeStack registers the Installable as a stack

func (StackWithResources) Install 

func (is StackWithResources) Install(ctx context.Context, progress io.Writer, context InstallationContext) error

Install installs or updates this stack into the directory specified by stack.Stack().

Installation is non-interactive, but will provide debugging output onto io. InstallationContext

type StagingContext 

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

StagingContext is a context used for Backupable and Snapshotable

func NewStagingContext 

func NewStagingContext(ctx context.Context, progress io.Writer, path string, manifest chan<- string) *StagingContext

NewStagingContext returns a new StagingContext

func (*StagingContext) AddDirectory 

func (sc *StagingContext) AddDirectory(path string, op func(context.Context) error) error

AddDirectory creates a new directory inside the destination. Passing the empty path creates the destination as a directory.

It then allows op to fill the file.

func (*StagingContext) AddFile 

func (sc *StagingContext) AddFile(path string, op func(ctx context.Context, file io.Writer) error) error

AddFile creates a new file at the provided path inside the destination. Passing the empty path creates the destination as a file.

It then allows op to write to the file.

The op function must not retain file. The underlying file does not need to be closed. AddFile will not return before op has returned.

func (*StagingContext) CopyDirectory 

func (sc *StagingContext) CopyDirectory(dst, src string) error

CopyDirectory copies a directory from src to dst.

func (*StagingContext) CopyFile 

func (sc *StagingContext) CopyFile(dst, src string) error

CopyFile copies a file from src to dst.

func (*StagingContext) Progress 

func (bc *StagingContext) Progress() io.Writer

Progress returns a writer to write progress information to.

type Still 

type Still struct {
	Config   *config.Config // the configuration of the distillery
	Upstream Upstream
}

Still represents the central part of a distillery. It is used inside the main distillery struct, as well as every component via [ComponentBase].

type Table 

type Table interface {
	Component

	// TableInfo returns information about a specific table
	TableInfo() TableInfo
}

Table is a component that manages a provided sql table

type TableInfo 

type TableInfo struct {
	Model reflect.Type // model is the model this type manages
	Name  string
}

type Updatable 

type Updatable interface {
	Component

	// Update updates or initializes the provided components.
	// It is called after the component has been installed (if applicable).
	//
	// It may send progress to the provided stream.
	//
	// Updating should be idempotent, meaning running it multiple times must not break the existing system.
	Update(ctx context.Context, progress io.Writer) error
}

Updatable represents a component with an Update method.

type Upstream 

type Upstream struct {
	SQL         HostPort
	Triplestore HostPort
	Solr        HostPort
}

Upstream contains the configuration for accessing remote configuration.

func (Upstream) SQLAddr 

func (us Upstream) SQLAddr() string

func (Upstream) SolrAddr 

func (us Upstream) SolrAddr() string

func (Upstream) TriplestoreAddr 

func (us Upstream) TriplestoreAddr() string

type UserDeleteHook 

type UserDeleteHook interface {
	Component

	// OnUserDelete is called right before a user is deleted
	OnUserDelete(ctx context.Context, user *models.User) error
}

UserDeleteHook represents a hook that is called just before a user is deleted

Source Files

View all Source files

Directories

Path Synopsis
api
Package api implements a common handler used by the api routes
 Package api implements a common handler used by the api routes
next
panel
policy
scopes
Package scopes implements and provides scopes used by the API
 Package scopes implements and provides scopes used by the API
tokens
logger
malt
purger
admin
admin/socket
assets
Package static implements serving of fully static resources
 Package static implements serving of fully static resources
cron
home
legal
list
logo
news
templating
sshkeys

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.