concourse

README

Concourse Resource Interface in Go

This repo specifies an opinionated interface for Concourse resources in Go. It simplifies resource implementations, by providing

• Unmarshaling and validating the request from JSON,
• Calling the implementation of the interface, and
• Validating and marshaling the response to JSON.

The interface is generic and expects concrete types for Source, Version and Params. You can add additional validation rules by annotating your types with the ones implemented by go-playground/validator.

For an example that uses this interface, check the Euro Exchange Rates Resource.

Documentation

Overview

Package concourse provides a type-safe interface for Concourse resources.

Index

• func CheckWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, ...) error
• func GetWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, ...) error
• func NewRootCommand[S any, V any, P any](resource Resource[S, V, P], name string) *cobra.Command
• func PutWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, ...) error
• type CheckRequest
  • func (r CheckRequest[S, V]) Validate() error
• type CheckResponse
  • func (r CheckResponse[V]) Validate() error
• type GetRequest
  • func (r GetRequest[S, V, P]) Validate() error
• type NameValuePair
• type PutRequest
  • func (r PutRequest[S, P]) Validate() error
• type Resource
• type Response
  • func (r Response[V]) Validate() error

Functions

func CheckWithValidation

func CheckWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, stdout, stderr io.Writer) error

func GetWithValidation

func GetWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, stdout, stderr io.Writer, destination string) error

func NewRootCommand

func NewRootCommand[S any, V any, P any](resource Resource[S, V, P], name string) *cobra.Command

NewRootCommand returns a Cobra command with three subcommands (check, get and put), suitable for a Concourse resource. Each command corresponds to the respective /opt/resource/{check,in,out} scripts.

Validation is performed on request and response. If you add struct tags to conrete Source (S) and Version (V) types, they will be checked, too. Check the validator package for details.

func PutWithValidation

func PutWithValidation[S any, V any, P any](ctx context.Context, resource Resource[S, V, P], stdin io.Reader, stdout, stderr io.Writer, source string) error

Types

type CheckRequest

type CheckRequest[S any, V any] struct {
	Source  S `json:"source" validate:"required"`
	Version V `json:"version" validate:"omitempty"`
}

func (CheckRequest[S, V]) Validate

func (r CheckRequest[S, V]) Validate() error

type CheckResponse

type CheckResponse[V any] []V

func (CheckResponse[V]) Validate

func (r CheckResponse[V]) Validate() error

type GetRequest

type GetRequest[S any, V any, P any] struct {
	Source  S `json:"source" validate:"required"`
	Version V `json:"version" validate:"required"`
	Params  P `json:"params"`
}

func (GetRequest[S, V, P]) Validate

func (r GetRequest[S, V, P]) Validate() error

type NameValuePair

type NameValuePair struct {
	Name  string `json:"name" validate:"required"`
	Value string `json:"value"`
}

type PutRequest

type PutRequest[S any, P any] struct {
	Source S `json:"source" validate:"required"`
	Params P `json:"params"`
}

func (PutRequest[S, P]) Validate

func (r PutRequest[S, P]) Validate() error

type Resource

type Resource[S any, V any, P any] interface {
	// Check is invoked to detect new versions of the resource.
	//
	// It is given the configured source and current version, and must return new versions as response, in
	// chronological order (oldest first, including the requested version if it's still valid).
	//
	// [Check]: https://concourse-ci.org/implementing-resource-types.html#resource-check
	Check(ctx context.Context, request CheckRequest[S, V], log io.Writer) (CheckResponse[V], error)

	// Get is invoked to fetch the resource and place it in the given directory.
	//
	// If is given the configured source, exact version of the resource to fetch, and configured parameters. It is
	// also passed the destination directory where the state of the resource is to be placed.
	//
	// The function must return a response that describes the fetched version, and may add metadata.
	//
	// [In]: https://concourse-ci.org/implementing-resource-types.html#resource-in
	Get(ctx context.Context, request GetRequest[S, V, P], log io.Writer, destination string) (*Response[V], error)

	// Put is invoked to store the resource as it is given in the passed directory.
	//
	// If is given the configured source and configured parameters. The function must a response that describes the
	// resulting version, and may add metadata.
	//
	// [Out]: https://concourse-ci.org/implementing-resource-types.html#resource-out
	Put(ctx context.Context, request PutRequest[S, P], log io.Writer, source string) (*Response[V], error)
}

type Response

type Response[V any] struct {
	Version  V               `json:"version" validate:"required"`
	Metadata []NameValuePair `json:"metadata,omitempty" validate:"dive"`
}

func (Response[V]) Validate

func (r Response[V]) Validate() error