Documentation
¶
Overview ¶
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Package trill houses a thin wrapper for communicating with podman and Docker via their REST API.
Index ¶
- Variables
- func NewPrefixedPrintf(action string, context string) func(format string, a ...any) (n int, err error)
- func NewPrefixedPrintfError(action string) func(format string, a ...any) (n int, err error)
- type Client
- func (c *Client) AttachHostTerminalToDevcontainer() (err error)
- func (c *Client) BuildContainerImage(contextPath string, dockerfilePath string, imageTag string, ...) (err error)
- func (c *Client) BuildDevcontainerImage(p *writ.Parser, imageTag string, skipIfAvailable bool, suppressOutput bool) error
- func (c *Client) Close() (err error)
- func (c *Client) DeployComposerProject(p *writ.Parser, projName string, imageTagPrefix string, ...) error
- func (c *Client) ExecInContainer(ctx context.Context, containerID string, p *writ.Parser, runInShell bool, ...) (err error)
- func (c *Client) ExecInDevcontainer(ctx context.Context, p *writ.Parser, runInShell bool, args ...string) error
- func (c *Client) InspectImage(imageTag string) (imageCfg *imagespec.DockerOCIImageConfig, err error)
- func (c *Client) IsImageTagAvailable(imageTag string) bool
- func (c *Client) PullContainerImage(imageTag string, skipIfAvailable bool, suppressOutput bool) (err error)
- func (c *Client) ResizeContainer(h uint, w uint) (err error)
- func (c *Client) StartContainer(p *writ.Parser, containerCfg *container.Config, hostCfg *container.HostConfig, ...) error
- func (c *Client) StartDevcontainerContainer(p *writ.Parser, imageTag string, containerName string) error
- func (c *Client) StopDevcontainer()
- func (c *Client) TeardownComposerProject() error
- type LifecycleEvents
- type Platform
- type PrivilegedPortElevator
- type StreamWriter
Constants ¶
This section is empty.
Variables ¶
var ErrLifecycleHandler = errors.New("lifecycle handler encountered an error")
ErrLifecycleHandler is a generic error thrown when the lifecycle handler encounters an error
Functions ¶
func NewPrefixedPrintf ¶
func NewPrefixedPrintf(action string, context string) func(format string, a ...any) (n int, err error)
NewPrefixedPrintf returns a function that can be used in place of fmt.Printf; every invocation prints out a standardized prefix before the rest of its arguments.
func NewPrefixedPrintfError ¶
NewPrefixedPrintfError returns a function that can be used in place of fmt.Printf when outputting errors; every invocation prints out a standardized prefix before the rest of its arguments.
Types ¶
type Client ¶
type Client struct {
ContainerID string // The internal ID the API assigned to the created container
// Channel to broadcast the devcontainer's (in a Composer project,
// the container named in the service field) lifecycle events on
DevcontainerLifecycleChan chan LifecycleEvents
DevcontainerLifecycleResp chan bool
Platform Platform // Platform details for any containers created
PrivilegedPortElevator PrivilegedPortElevator // If non-nil, will be called whenever a binding for a port number < 1024 is encountered; its return value will be used in place of the original port
SocketAddr string // The socket/named pipe used to communicate with the server
// contains filtered or unexported fields
}
Client holds metadata for communicating with Podman/Docker.
func NewClient ¶
NewClient returns a Client that's set to communicate with Podman/Docker via socketAddr.
If it encounters an error creating the underlying connection, it panics.
func (*Client) AttachHostTerminalToDevcontainer ¶
AttachHostTerminalToDevcontainer attempts to route input from the terminal into the container's pseudo-TTY, and redirect the pseudo-TTY's output to the host terminal.
This allows usage of the container in a terminal as one would, e.g., a regular shell
func (*Client) BuildContainerImage ¶
func (c *Client) BuildContainerImage(contextPath string, dockerfilePath string, imageTag string, buildOpts *mobyclient.ImageBuildOptions, skipIfAvailable bool, suppressOutput bool) (err error)
BuildContainerImage builds the OCI image to be used by the devcontainer.
Requires metadata parsed from a devccontainer.json configuration file and a tag to apply to the built OCI image.
TODO: Add a flag to toggle deletion of the context tarball after the creation of the OCI image
func (*Client) BuildDevcontainerImage ¶
func (c *Client) BuildDevcontainerImage(p *writ.Parser, imageTag string, skipIfAvailable bool, suppressOutput bool) error
BuildDevcontainerImage builds an OCI image based on options in a devcontainer.json.
This is a very thin wrapper over BuildContainerImage.
func (*Client) DeployComposerProject ¶
func (c *Client) DeployComposerProject(p *writ.Parser, projName string, imageTagPrefix string, skipBuildIfAvailable bool, skipPullIfAvailable bool, suppressOutput bool) error
DeployComposerProject provisions a Composer project as referenced by a devcontainer.json configuration.
It is not dissimlar for running `docker compose up` inside your codebase.
func (*Client) ExecInContainer ¶
func (c *Client) ExecInContainer(ctx context.Context, containerID string, p *writ.Parser, runInShell bool, args ...string) (err error)
ExecInContainer runs a command inside a container designated by containerID.
If runInShell is true, args is ran via `/bin/sh -c`; otherwise, args[0] is treated as the program name.
func (*Client) ExecInDevcontainer ¶
func (c *Client) ExecInDevcontainer(ctx context.Context, p *writ.Parser, runInShell bool, args ...string) error
ExecInDevcontainer runs a command inside the designated devcontainer (i.e., the lone container in non-Composer configurations, or the one named in the service field otherwise).
func (*Client) InspectImage ¶
func (c *Client) InspectImage(imageTag string) (imageCfg *imagespec.DockerOCIImageConfig, err error)
InspectImage is a very thin wrapper around the ImageInspect API call.
func (*Client) IsImageTagAvailable ¶
IsImageTagAvailable returns whether or not the container runtime already has an image tagged imageTag.
func (*Client) PullContainerImage ¶
func (c *Client) PullContainerImage(imageTag string, skipIfAvailable bool, suppressOutput bool) (err error)
PullContainerImage pulls the OCI image from a remtoe registry so it can be used in the creation of a devcontainer.
TODO: Implement a privilege function to support authentication so images can be pulled from private repositories
func (*Client) ResizeContainer ¶
ResizeContainer sets the container's internal pseudo-TTY height and width to the passed in values.
func (*Client) StartContainer ¶
func (c *Client) StartContainer(p *writ.Parser, containerCfg *container.Config, hostCfg *container.HostConfig, containerName string, isDevcontainer bool) error
StartContainer creates a container based on the passed in arguments then starts it.
func (*Client) StartDevcontainerContainer ¶
func (c *Client) StartDevcontainerContainer(p *writ.Parser, imageTag string, containerName string) error
StartDevcontainerContainer starts and attaches to a container based on configuration from devcontainer.json.
Requires metadata parsed from a devcontainer.json config, the tag/image name for the OCI image to use as base, and a name for the created container.
func (*Client) StopDevcontainer ¶
func (c *Client) StopDevcontainer()
StopDevcontainer signals the devcontainer to terminate and then subsequently removed.
There is normally no reason to call this directly: this is intended to assist with cleanup when errors are encountered.
func (*Client) TeardownComposerProject ¶
TeardownComposerProject tears down a provisioned Composer project's resources.
It is not dissimlar to running `docker compose down` inside your codebase.
type LifecycleEvents ¶
type LifecycleEvents uint
LifecycleEvents is a list of event codes that are fired at several points during a devcontainer's lifecycle
const ( LifecycleInitialize LifecycleEvents = iota LifecycleOnCreate LifecycleUpdate LifecyclePostCreate LifecyclePostStart LifecyclePostAttach )
During a devcontainer's lifecycle, several events are tracked
type PrivilegedPortElevator ¶
PrivilegedPortElevator is a function that Client can use to convert privileged ports it encounters into non-privileged ports.
It is passed the privileged port number and the return value is used in the original port's stead.
There is no check performed on the return value to see if it actually produces a port number beyond the privileged port range.
type StreamWriter ¶
type StreamWriter struct {
// contains filtered or unexported fields
}
StreamWriter is a thin custom wrapper for outputting streaming messages with a prefix at the beginning of each line.
func NewPrefixedStreamWriter ¶
func NewPrefixedStreamWriter(w io.Writer, action string, context string) *StreamWriter
NewPrefixedStreamWriter returns a standardized prefixed writer for streams.
func NewStreamWriter ¶
func NewStreamWriter(w io.Writer, prefix string) *StreamWriter
NewStreamWriter returns a wrapper for an io.Writer
Source Files