interfaces

package
v0.9.4 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ByName = func(name string) (iface Interface, err error) {
	panic("ByName is unset, import interfaces/builtin to initialize this")
}

ByName returns an Interface for the given interface name. Note that in order for this to work properly, the package "interfaces/builtin" must also eventually be imported to populate the full list of interfaces.

Functions

func BeforeConnectPlug 

func BeforeConnectPlug(iface Interface, plug *ConnectedPlug) error

func BeforePreparePlug 

func BeforePreparePlug(iface Interface, plugInfo *sdk.PlugInfo) error

BeforePreparePlug sanitizes a plug with a given interface.

func BeforePrepareSlot 

func BeforePrepareSlot(iface Interface, slotInfo *sdk.SlotInfo) error

Sanitize slot with a given interface.

func PermanentPlugServiceSnippets 

func PermanentPlugServiceSnippets(iface Interface, plug *sdk.PlugInfo) (snips []string, err error)

PermanentPlugServiceSnippets will return the set of snippets for the systemd service unit that should be generated for a sdk with the specified plug. The list returned is not unique, callers must de-duplicate themselves. The plug is provided because the snippet may depend on plug attributes for example. The plug is sanitized before the snippets are returned.

Types

type Attrer 

type Attrer interface {
	// Attr returns attribute value for given path, or an error. Dotted paths are supported.
	Attr(path string, value any) error
	// Lookup returns attribute value for given path, or false. Dotted paths are supported.
	Lookup(path string) (value any, ok bool)
}

Attrer is an interface with Attr getter method common to ConnectedSlot, ConnectedPlug, PlugInfo and SlotInfo types.

type ConnPlugSanitizer 

type ConnPlugSanitizer interface {
	BeforeConnectPlug(plug *ConnectedPlug) error
}

ConnPlugSanitizer can be implemented by Interfaces that have reasons to sanitize their plugs specifically before a connection is performed.

type ConnRef 

type ConnRef struct {
	PlugRef sdk.PlugRef
	SlotRef sdk.SlotRef
}

ConnRef holds information about plug and slot reference that form a particular connection.

func NewConnRef 

func NewConnRef(plug *sdk.PlugInfo, slot *sdk.SlotInfo) *ConnRef

NewConnRef creates a connection reference for given plug and slot

func ParseConnRef 

func ParseConnRef(id string) (*ConnRef, error)

ParseConnRef parses an ID string

func (*ConnRef) ID 

func (conn *ConnRef) ID() string

ID returns a string identifying a given connection.

func (*ConnRef) SortsBefore 

func (conn *ConnRef) SortsBefore(other *ConnRef) bool

SortsBefore returns true when connection should be sorted before the other

type ConnectedPlug 

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

ConnectedPlug represents a plug that is connected to a slot.

func NewConnectedPlug 

func NewConnectedPlug(plug *sdk.PlugInfo, staticAttrs, dynamicAttrs map[string]any) *ConnectedPlug

NewConnectedPlug creates an object representing a connected plug.

func (*ConnectedPlug) Attr 

func (plug *ConnectedPlug) Attr(key string, val any) error

Attr returns a dynamic attribute with the given name. It falls back to returning static attribute if dynamic one doesn't exist. Error is returned if neither dynamic nor static attribute exist.

func (*ConnectedPlug) CheckBound 

func (p *ConnectedPlug) CheckBound() (*ConnRef, bool)

func (*ConnectedPlug) DynamicAttrs 

func (plug *ConnectedPlug) DynamicAttrs() map[string]any

DynamicAttrs returns all dynamic attributes.

func (*ConnectedPlug) Interface 

func (plug *ConnectedPlug) Interface() string

Interface returns the name of the interface for this plug.

func (*ConnectedPlug) Lookup 

func (plug *ConnectedPlug) Lookup(path string) (any, bool)

func (*ConnectedPlug) Name 

func (plug *ConnectedPlug) Name() string

Name returns the name of this plug.

func (*ConnectedPlug) Ref 

func (plug *ConnectedPlug) Ref() sdk.PlugRef

Ref returns the PlugRef for this plug.

func (*ConnectedPlug) Sdk 

func (plug *ConnectedPlug) Sdk() *sdk.Info

sdk returns the sdk Info of this plug.

func (*ConnectedPlug) SetAttr 

func (plug *ConnectedPlug) SetAttr(key string, value any) error

SetAttr sets the given dynamic attribute. Error is returned if the key is already used by a static attribute.

func (*ConnectedPlug) StaticAttr 

func (plug *ConnectedPlug) StaticAttr(key string, val any) error

StaticAttr returns a static attribute with the given key, or error if attribute doesn't exist.

func (*ConnectedPlug) StaticAttrs 

func (plug *ConnectedPlug) StaticAttrs() map[string]any

StaticAttrs returns all static attributes.

type ConnectedSlot 

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

ConnectedSlot represents a slot that is connected to a plug.

func NewConnectedSlot 

func NewConnectedSlot(slot *sdk.SlotInfo, staticAttrs, dynamicAttrs map[string]any) *ConnectedSlot

NewConnectedSlot creates an object representing a connected slot.

func (*ConnectedSlot) Attr 

func (slot *ConnectedSlot) Attr(key string, val any) error

Attr returns a dynamic attribute with the given name. It falls back to returning static attribute if dynamic one doesn't exist. Error is returned if neither dynamic nor static attribute exist.

func (*ConnectedSlot) DynamicAttrs 

func (slot *ConnectedSlot) DynamicAttrs() map[string]any

DynamicAttrs returns all dynamic attributes.

func (*ConnectedSlot) Interface 

func (slot *ConnectedSlot) Interface() string

Interface returns the name of the interface for this slot.

func (*ConnectedSlot) Lookup 

func (slot *ConnectedSlot) Lookup(path string) (any, bool)

func (*ConnectedSlot) Name 

func (slot *ConnectedSlot) Name() string

Name returns the name of this slot.

func (*ConnectedSlot) Ref 

func (slot *ConnectedSlot) Ref() sdk.SlotRef

Ref returns the SlotRef for this slot.

func (*ConnectedSlot) Sdk 

func (slot *ConnectedSlot) Sdk() *sdk.Info

sdk returns the sdk Info of this slot.

func (*ConnectedSlot) SetAttr 

func (slot *ConnectedSlot) SetAttr(key string, value any) error

SetAttr sets the given dynamic attribute. Error is returned if the key is already used by a static attribute.

func (*ConnectedSlot) StaticAttr 

func (slot *ConnectedSlot) StaticAttr(key string, val any) error

StaticAttr returns a static attribute with the given key, or error if attribute doesn't exist.

func (*ConnectedSlot) StaticAttrs 

func (slot *ConnectedSlot) StaticAttrs() map[string]any

StaticAttrs returns all static attributes.

type Connection 

type Connection struct {
	Plug *ConnectedPlug
	Slot *ConnectedSlot
}

Connection represents a connection between a particular plug and slot.

func (*Connection) Interface 

func (conn *Connection) Interface() string

Interface returns the name of the interface for this connection.

type Info 

type Info struct {
	Name    string
	Summary string
	DocURL  string
	Plugs   []*sdk.PlugInfo
	Slots   []*sdk.SlotInfo
}

Info holds information about a given interface and its instances.

type InfoOptions 

type InfoOptions struct {
	Names     []string
	Doc       bool
	Plugs     bool
	Slots     bool
	Connected bool
}

InfoOptions describes options for Info.

Names: return just this subset if non-empty. Doc: return documentation. Plugs: return information about plugs. Slots: return information about slots. Connected: only consider interfaces with at least one connection.

type Interface 

type Interface interface {
	// Unique and public name of this interface.
	Name() string

	// AutoConnect returns whether plug and slot should be
	// implicitly auto-connected assuming there will be an
	// unambiguous connection candidate and declaration-based checks
	// allow.
	AutoConnect(plug *sdk.PlugInfo, slot *sdk.SlotInfo) bool
}

Interface describes a group of interchangeable capabilities with common features. Interfaces act as a contract between system builders, application developers and end users.

type Interfaces 

type Interfaces struct {
	Plugs       []*sdk.PlugInfo
	Slots       []*sdk.SlotInfo
	Connections []*ConnRef
}

Interfaces holds information about a list of plugs, slots and their connections.

type NoPlugOrSlotError 

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

NoPlugOrSlotError is returned by Disconnect() if either the plug or slot does no exist.

func (*NoPlugOrSlotError) Error 

func (e *NoPlugOrSlotError) Error() string

type NotConnectedError 

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

NotConnectedError is returned by Disconnect() if the requested connection does not exist.

func (*NotConnectedError) Error 

func (e *NotConnectedError) Error() string

type PlugSanitizer 

type PlugSanitizer interface {
	BeforePreparePlug(plug *sdk.PlugInfo) error
}

PlugSanitizer can be implemented by Interfaces that have reasons to sanitize their plugs.

type PolicyFunc 

type PolicyFunc func(*ConnectedPlug, *ConnectedSlot) (bool, error)

type Repository 

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

Repository stores all known plugs and slots and ifaces.

func NewRepository 

func NewRepository() *Repository

NewRepository creates an empty plug repository.

func (*Repository) AddBackend 

func (r *Repository) AddBackend(backend SecurityBackend) error

AddBackend adds the provided security backend to the repository.

func (*Repository) AddInterface 

func (r *Repository) AddInterface(i Interface) error

AddInterface adds the provided interface to the repository.

func (*Repository) AddPlug 

func (r *Repository) AddPlug(plug *sdk.PlugInfo) error

AddPlug adds a plug to the repository. Plug names must be valid sdk names, as defined by ValidateName. Plug name must be unique within a particular sdk.

func (*Repository) AddSdk 

func (r *Repository) AddSdk(sdkInfo *sdk.Info) error

AddSdk adds plugs and slots declared by the given sdk to the repository.

AddSdk doesn't change existing plugs/slots. The caller is responsible for ensuring that the sdk is not present in the repository in any way prior to calling this function. If this constraint is violated then no changes are made and an error is returned.

Each added plug/slot is validated according to the corresponding interface. Unknown interfaces and plugs/slots that don't validate are not added. Information about those failures are returned to the caller.

func (*Repository) AddSlot 

func (r *Repository) AddSlot(slot *sdk.SlotInfo) error

AddSlot adds a new slot to the repository. Adding a slot with invalid name returns an error. Adding a slot that has the same name and sdk name as another slot returns an error.

func (*Repository) AllInterfaces 

func (r *Repository) AllInterfaces() []Interface

AllInterfaces returns all the interfaces added to the repository, ordered by name.

func (*Repository) AllPlugs 

func (r *Repository) AllPlugs(interfaceName string) []*sdk.PlugInfo

AllPlugs returns all plugs of the given interface. If interfaceName is the empty string, all plugs are returned.

func (*Repository) AllSlots 

func (r *Repository) AllSlots(interfaceName string) []*sdk.SlotInfo

AllSlots returns all slots of the given interface. If interfaceName is the empty string, all slots are returned.

func (*Repository) AutoConnectCandidatePlugs 

func (r *Repository) AutoConnectCandidatePlugs(projectId, workshop, slotSdkName, slotName string, policyCheck func(*ConnectedPlug, *ConnectedSlot) (bool, error)) []*sdk.PlugInfo

AutoConnectCandidatePlugs finds and returns viable auto-connection candidates for a given slot.

func (*Repository) AutoConnectCandidateSlots 

func (r *Repository) AutoConnectCandidateSlots(projectId, workshop, plugSdkName, plugName string, policyCheck func(*ConnectedPlug, *ConnectedSlot) (bool, error)) []*sdk.SlotInfo

AutoConnectCandidateSlots finds and returns viable auto-connection candidates for a given plug.

func (*Repository) Backends 

func (r *Repository) Backends() []SecurityBackend

Backends returns all the security backends. The order is the same as the order in which they were inserted.

func (*Repository) Connect 

func (r *Repository) Connect(ref *ConnRef, plugStaticAttrs, plugDynamicAttrs, slotStaticAttrs, slotDynamicAttrs map[string]any, policyCheck PolicyFunc) (*Connection, error)

Connect establishes a connection between a plug and a slot. The plug and the slot must have the same interface. When connections are reloaded policyCheck is null (we don't check policy again).

func (*Repository) Connected 

func (r *Repository) Connected(projectId, workshop, sdkName, plugOrSlotName string) ([]*ConnRef, error)

Connected returns references for all connections that are currently established with the provided plug or slot.

func (*Repository) Connection 

func (r *Repository) Connection(connRef *ConnRef) (*Connection, error)

Connection returns the specified Connection object or an error.

func (*Repository) Connections 

func (r *Repository) Connections(projectId, workshop, sdk string) ([]*ConnRef, error)

func (*Repository) Disconnect 

func (r *Repository) Disconnect(plugProjectId, plugWorkshop, plugSdkName, plugName, slotProjectId, slotWorkshop, slotSdkName, slotName string) error

Disconnect disconnects the named plug from the slot of the given sdk.

Disconnect() finds a specific slot and a specific plug and disconnects that plug from that slot. It is an error if plug or slot cannot be found or if the connect does not exist.

func (*Repository) DisconnectAll 

func (r *Repository) DisconnectAll(conns []*ConnRef)

DisconnectAll disconnects all provided connection references.

func (*Repository) DisconnectSdk 

func (r *Repository) DisconnectSdk(projectId, workshop, sdkName string) ([]*sdk.Info, error)

DisconnectSdk disconnects all the connections to and from a given sdk.

The return value is a list of names that were affected.

func (*Repository) Info 

func (r *Repository) Info(opts *InfoOptions) []*Info

Info returns information about interfaces in the system.

If names is empty then all interfaces are considered. Query options decide which data to return but can also skip interfaces without connections. See the documentation of InfoOptions for details.

func (*Repository) Interface 

func (r *Repository) Interface(interfaceName string) Interface

Interface returns an interface with a given name.

func (*Repository) Interfaces 

func (r *Repository) Interfaces() *Interfaces

Interfaces returns object holding a lists of all the plugs and slots and their connections.

func (*Repository) Plug 

func (r *Repository) Plug(projectId, workshop, sdkName, plugName string) *sdk.PlugInfo

Plug returns the specified plug from the named sdk.

func (*Repository) Plugs 

func (r *Repository) Plugs(projectId, workshop, sdkName string) []*sdk.PlugInfo

Plugs returns the plugs offered by the named sdk.

func (*Repository) RemovePlug 

func (r *Repository) RemovePlug(projectId, workshop, sdkName, plugName string) error

RemovePlug removes the named plug provided by a given sdk. The removed plug must exist and must not be used anywhere.

func (*Repository) RemoveSdk 

func (r *Repository) RemoveSdk(projectId, workshop, sdkName string) error

RemoveSdk removes all the plugs and slots associated with a given sdk.

This function can be used to implement sdk removal or, when used along with AddSdk, sdk upgrade.

RemoveSdk does not remove connections. The caller is responsible for ensuring that connections are broken before calling this method. If this constraint is violated then no changes are made and an error is returned.

func (*Repository) RemoveSlot 

func (r *Repository) RemoveSlot(projectId, workshop, sdkName, slotName string) error

RemoveSlot removes a named slot from the given sdk. Removing a slot that doesn't exist returns an error. Removing a slot that is connected to a plug returns an error.

func (*Repository) ResolveConnect 

func (r *Repository) ResolveConnect(plugProjectId, plugWorkshop, plugSdkName, plugName, slotProjectId, slotWorkshop, slotSdkName, slotName string) (*ConnRef, error)

ResolveConnect resolves potentially missing plug or slot names and returns a fully populated connection reference.

func (*Repository) SdkSpecification 

func (r *Repository) SdkSpecification(ctx context.Context, securitySystem SecuritySystem, sdkInfo sdk.Ref) (Specification, error)

SdkSpecification returns the specification of a given sdk in a given security system.

func (*Repository) Slot 

func (r *Repository) Slot(projectId, workshop, sdkName, slotName string) *sdk.SlotInfo

Slot returns the specified slot from the named sdk.

func (*Repository) Slots 

func (r *Repository) Slots(projectId, workshop, sdkName string) []*sdk.SlotInfo

Slots returns the slots offered by the named sdk.

type SecurityBackend 

type SecurityBackend interface {
	// Initialize performs any initialization required by the backend.
	// It is called during workshopd startup process.
	Initialize() error

	// Name returns the name of the backend.
	// This is intended for diagnostic messages.
	Name() SecuritySystem

	// Setup creates and loads security artefacts specific to a given sdk.
	// This method should be called after changing plug, slots, connections
	// between them.
	Setup(context context.Context, sdkRef sdk.Ref, repo *Repository) error

	// Remove removes and unloads security artefacts of a given sdk.
	//
	// This method should be called during the process of removing an sdk.
	Remove(context context.Context, sdkRef sdk.Ref) error

	// NewSpecification returns a new specification associated with this backend.
	NewSpecification(user string, sdk string) (Specification, error)
}

SecurityBackend abstracts interactions between the interface system and the needs of a particular security system.

type SecuritySystem 

type SecuritySystem string

SecuritySystem is a name of a security system. 

const (
	// SecurityLxdDevice creates LXD device configurations (mount, GPU, etc.)
	SecurityLxdDevice SecuritySystem = "lxd-device"
)

type SideArity 

type SideArity interface {
	SlotsPerPlugAny() bool
}

SideArity conveys the arity constraints for an allowed auto-connection. ATM only slots-per-plug might have an interesting non-default value. See: https://forum.snapcraft.io/t/plug-slot-declaration-rules-greedy-plugs/12438

type SlotSanitizer 

type SlotSanitizer interface {
	BeforePrepareSlot(slot *sdk.SlotInfo) error
}

SlotSanitizer can be implemented by Interfaces that have reasons to sanitize their slots.

type Specification 

type Specification interface {
	// AddPermanentSlot records side-effects of having a slot.
	AddPermanentSlot(iface Interface, slot *sdk.SlotInfo) error
	// AddPermanentPlug records side-effects of having a plug.
	AddPermanentPlug(iface Interface, plug *sdk.PlugInfo) error
	// AddConnectedSlot records side-effects of having a connected slot.
	AddConnectedSlot(iface Interface, plug *ConnectedPlug, slot *ConnectedSlot) error
	// AddConnectedPlug records side-effects of having a connected plug.
	AddConnectedPlug(iface Interface, plug *ConnectedPlug, slot *ConnectedSlot) error
}

Specification describes interactions between backends and interfaces.

type StaticInfo 

type StaticInfo struct {
	Summary string `json:"summary,omitempty"`
	DocURL  string `json:"doc-url,omitempty"`

	// AffectsPlugOnRefresh tells if refreshing of a sdk with a slot of this interface
	// is disruptive for the sdk on the plug side (when the interface is connected),
	// meaning that a refresh of the slot-side affects sdk(s) on the plug side
	AffectsPlugOnRefresh bool `json:"affects-plug-on-refresh,omitempty"`

	// BaseDeclarationPlugs defines an optional extension to the base-declaration assertion relevant for this interface.
	BaseDeclarationPlugs string
	// BaseDeclarationSlots defines an optional extension to the base-declaration assertion relevant for this interface.
	BaseDeclarationSlots string
}

StaticInfo describes various static-info of a given interface.

The Summary must be a one-line string of length suitable for listing views. The DocURL can point to website (e.g. a forum thread) that goes into more depth and documents the interface in detail.

func StaticInfoOf 

func StaticInfoOf(iface Interface) (si StaticInfo)

StaticInfoOf returns the static-info of the given interface.

Source Files

View all Source files

Directories

Path Synopsis
Package policy implements the declaration based policy checks for connecting or permitting installation of sdks based on their slots and plugs.
 Package policy implements the declaration based policy checks for connecting or permitting installation of sdks based on their slots and plugs.

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.