forge

README

forge

Have you ever had to swap to using a new CI system? Twice? Three times? Done with searching for a replacement for each Action, CloudBuilder or resource that you were using in your old one? Tired of waiting minutes for feedback on each iteration of dealing with the quirks of your new one?

Forge is here to help.

Forge is a library and CLI for running reusable steps from various proprietary CI systems using a pluggable container runtime. This, for example, makes the functionality provided to GitHub Actions easily consumable (or testable) by users of other CI systems.

(Learn more)[docs/index.md].

Documentation

Index

• Variables
• func SemVer() string
• type Container
• type ContainerConfig
• type ContainerRuntime
• type Drains
  • func StdDrains() *Drains
  • func (d *Drains) GoString() string
  • func (d *Drains) ToStreams(in io.Reader) *Streams
• type Foundry
  • func NewFoundry(containerRuntime ContainerRuntime) *Foundry
  • func (f *Foundry) GoString() string
  • func (f *Foundry) Process(ctx context.Context, ore Ore, drains *Drains) error
• type Image
• type Mount
• type Ore
• type Streams
  • func StdStreams() *Streams
  • func StdTerminalStreams() (*Streams, func() error)
  • func TerminalStreams(stdin io.Reader, stdout, stderr io.Writer) (*Streams, func() error, error)
• type Volume

Examples

• Foundry.Process

Variables

var DefaultDetachKeys = "ctrl-d"

DefaultDetachKeys are the default key combinations to use when detaching from a Container that has been attached to.

var VersionCore = "0.15.1"

VersionCore is the SemVer version core of forge. Meant to be be overridden at build time, but kept up-to-date sometimes to best support `go install`.

Functions

func SemVer

func SemVer() string

SemVer returns the semantic version of forge as built from VersionCore and debug build info.

Types

type Container

type Container interface {
	GetID() string

	CopyTo(context.Context, string, io.Reader) error
	CopyFrom(context.Context, string) (io.ReadCloser, error)

	Run(context.Context, *Streams) (int, error)
	Start(context.Context) error
	Restart(context.Context) error
	Exec(context.Context, *ContainerConfig, *Streams) (int, error)

	Stop(context.Context) error
	Remove(context.Context) error
	Kill(context.Context) error
}

Container represents a container created by a ContainerRuntime.

type ContainerConfig

type ContainerConfig struct {
	Entrypoint []string `json:"entrypoint,omitempty"`
	Cmd        []string `json:"cmd,omitempty"`
	WorkingDir string   `json:"working_dir,omitempty"`
	Env        []string `json:"env,omitempty"`
	User       string   `json:"user,omitempty"`
	Privileged bool     `json:"privileged,omitempty"`
	Mounts     []Mount  `json:"mounts,omitempty"`
}

ContainerConfig is the configuration that is used to create a container or an exec in a running container.

type ContainerRuntime

type ContainerRuntime interface {
	GetContainer(context.Context, string) (Container, error)
	CreateContainer(context.Context, Image, *ContainerConfig) (Container, error)
	PullImage(context.Context, string) (Image, error)
	CreateVolume(context.Context, string) (Volume, error)
	Close() error
}

ContainerRuntime represents the functionality needed by Ores to pull OCI images and run containers when being processed.

type Drains

type Drains struct {
	Out, Err io.Writer
	Tty      bool
}

Drains represents only outward streams from an Ore, namely stdout and stderr.

func StdDrains

func StdDrains() *Drains

StdDrains returns a Drains draining to os.Stdout and os.Stderr.

func (*Drains) GoString

func (d *Drains) GoString() string

GoString implements fmt.GoStringer.

func (*Drains) ToStreams

func (d *Drains) ToStreams(in io.Reader) *Streams

ToStreams turns a Drains to a Streams for use by Ores to pass to a Container.

type Foundry

type Foundry struct {
	ContainerRuntime
}

Foundry is a wrapper around a ContainerRuntime for processing Ores.

func NewFoundry

func NewFoundry(containerRuntime ContainerRuntime) *Foundry

NewFoundry returns a Foundry.

func (*Foundry) GoString

func (f *Foundry) GoString() string

GoString implements fmt.GoStringer.

func (*Foundry) Process

func (f *Foundry) Process(ctx context.Context, ore Ore, drains *Drains) error

Process Liquifies the Ore and returns the resulting Metal.

Example

Checkout https://github.com/frantjc/forge using https://github.com/actions/checkout, grepping to only print debug logs.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/docker/docker/client"
	"github.com/frantjc/forge"
	"github.com/frantjc/forge/githubactions"
	"github.com/frantjc/forge/ore"
	"github.com/frantjc/forge/runtime/docker"
)

func main() {
	ctx := context.Background()

	cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	globalContext := githubactions.NewGlobalContextFromEnv()
	globalContext.EnableDebug()
	globalContext.GitHubContext.Repository = "frantjc/forge"

	if err = forge.NewFoundry(docker.New(cli)).Process(
		ctx,
		&ore.Lava{
			From: &ore.Action{
				Uses:          "actions/checkout@v4",
				GlobalContext: globalContext,
			},
			To: &ore.Pure{
				Image:      "alpine:3.19",
				Entrypoint: []string{"grep", "debug"},
			},
		},
		forge.StdDrains(),
	); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

type Image

type Image interface {
	Manifest() (*imagespecsv1.Manifest, error)
	Config() (*imagespecsv1.ImageConfig, error)
	Digest() (digest.Digest, error)
	Blob() io.Reader
	Name() string
}

Image represents a image pulled by a ContainerRuntime. Used to create Containers from.

type Mount

type Mount struct {
	Source      string `json:"source,omitempty"`
	Destination string `json:"destination,omitempty"`
}

type Ore

type Ore interface {
	Liquify(context.Context, ContainerRuntime, *Drains) error
}

Ore represents one or more sequential containerized commands. Ores are meant to represent the entire input to said commands, so that if two Ore's match, their results should be the same. Because of this, Ores can be cached.

type Streams

type Streams struct {
	*Drains
	In         io.Reader
	DetachKeys string
}

Streams represents streams to and from a process inside of a Container.

func StdStreams

func StdStreams() *Streams

StdStreams returns a Streams consisting of os.Stdin, os.Stdout and os.Stderr.

func StdTerminalStreams

func StdTerminalStreams() (*Streams, func() error)

StdTerminalStreams creates a Streams with os.Stdin, os.Stdout and os.Stderr made raw and a restore function to return them to their previous state. For use with attaching to a shell inside of a Container.

func TerminalStreams

func TerminalStreams(stdin io.Reader, stdout, stderr io.Writer) (*Streams, func() error, error)

TerminalStreams creates a Streams with each of the given streams that is a terminal made raw and a restore function to return them to their previous states. For use with attaching to a shell inside of a Container.

type Volume

type Volume interface {
	GetID() string
	Remove(context.Context) error
}

Volume represents a volume created by a ContainerRuntime which can be attached to a Container via its ContainerConfig.Mounts.