resources

Documentation

Overview

Package resources holds what every resource kind has in common, including how a blueprint resource is named, referred to and resolved, and the provider interface a platform module implements.

The vocabulary for working with a resource lives in the package for its kind: github.com/newstack-cloud/celerity-go-sdk/resources/datastore, github.com/newstack-cloud/celerity-go-sdk/resources/bucket and the rest. Implementations are per provider and live in their own modules, such as resources/aws, so that an application that never touches S3 does not compile the AWS SDK into its binary.

A handle is obtained by naming the blueprint resource:

uploads := resources.Bucket(app, "uploadsBucket")
orders := resources.Datastore(app, "ordersTable")

Those calls are also what the extraction pass reads in order to work out which resources each handler reaches, and so which IAM grants it needs, so the name is expected to be a compile-time constant.

Index

• Constants
• func Bucket(host Host, name ...string) bucket.Store
• func Cache(host Host, name ...string) cache.Client
• func Datastore(host Host, name ...string) datastore.Client
• func Queue(host Host, name ...string) queue.Client
• func RegisterProvider(p Provider)
• func RegisteredProviders() []string
• func Release(ctx context.Context) error
• func SQLDatabase(host Host, name ...string) sqldb.Client
• func Topic(host Host, name ...string) topic.Client
• type Closer
• type Fields
  • func (f Fields) Boolean(ctx context.Context, suffix string, fallback bool) (bool, error)
  • func (f Fields) Number(ctx context.Context, suffix string, fallback int) (int, error)
  • func (f Fields) Optional(ctx context.Context, suffix, fallback string) (string, error)
  • func (f Fields) Reader() *Reader
  • func (f Fields) Required(ctx context.Context, suffix string) (string, error)
• type Host
• type Kind
• type MissingProviderError
  • func (e *MissingProviderError) Error() string
• type Provider
  • func DetectedProvider() (Provider, bool)
  • func FallbackProvider(excluding string) (Provider, bool)
• type Reader
  • func (r *Reader) Boolean(ctx context.Context, suffix string, fallback bool) bool
  • func (r *Reader) Err() error
  • func (r *Reader) Number(ctx context.Context, suffix string, fallback int) int
  • func (r *Reader) Optional(ctx context.Context, suffix, fallback string) string
  • func (r *Reader) Required(ctx context.Context, suffix string) string
• type Ref
  • func (r Ref) Field(ctx context.Context, suffix string) (string, bool, error)
  • func (r Ref) ID(ctx context.Context) (string, error)
  • func (r Ref) String() string

Constants

const (
	AuthPassword = "password"
	AuthIAM      = "iam"
)

The ways a deployment says a cache or a database is reached, written under the resource's own key as _authMode.

const DefaultName = "default"

DefaultName is the reference emitted when a handle is taken without a name, meaning the only resource of its type. It is resolved against the blueprint by the CLI rather than by the SDK, which cannot see the blueprint.

const FieldRegion = "_region"

FieldRegion is the suffix a deployment records a resource's region under, where the resource is not in the application's own region.

Absent for everything a deployment created for this application, which is where the application is. Written for a resource the blueprint declares as external, which may be somewhere else, and read through Fields.Optional so that absence means the application's own region rather than a failure.

Named here rather than in a provider module because the suffix is the deploy engine's: it writes one shape for every language.

Functions

func Bucket

func Bucket(host Host, name ...string) bucket.Store

Bucket returns a handle to a blueprint bucket resource.

Called with no name it refers to the only bucket the blueprint declares, which the CLI resolves.

func Cache

func Cache(host Host, name ...string) cache.Client

Cache returns a handle to a blueprint cache resource.

func Datastore

func Datastore(host Host, name ...string) datastore.Client

Datastore returns a handle to a blueprint data store resource.

func Queue

func Queue(host Host, name ...string) queue.Client

Queue returns a handle to a blueprint queue resource.

func RegisterProvider

func RegisterProvider(p Provider)

RegisterProvider adds a resource provider to the set considered at startup.

It is called from a provider package's init function and panics on a duplicate name.

func RegisteredProviders

func RegisteredProviders() []string

RegisteredProviders returns every linked provider, by name and sorted.

func Release

func Release(ctx context.Context) error

Release gives back what the linked providers hold.

Called by [celerity.Run] when serving ends, so an application does not have to. Providers that hold nothing are skipped, and a provider that fails to release is reported without stopping the rest.

Nothing calls this on a serverless platform, where an execution environment is frozen between invocations and torn down without warning rather than shut down. A pool there is given up with the environment.

func SQLDatabase

func SQLDatabase(host Host, name ...string) sqldb.Client

SQLDatabase returns a handle to a blueprint SQL database resource.

func Topic

func Topic(host Host, name ...string) topic.Client

Topic returns a handle to a blueprint topic resource.

Types

type Closer

type Closer interface {
	Close(ctx context.Context) error
}

Closer is a provider that holds something worth releasing when an application stops: a connection pool, a client with a background goroutine.

Optional, and asserted for rather than part of Provider: a bucket and a queue are HTTP clients a process can simply stop using, where a database's open connections and a cache's sockets are worth giving back.

type Fields

type Fields struct {
	Ref Ref
}

Fields reads what a deployment recorded about a resource.

A bucket or a queue is one identifier and doesn't need this. A cache or a database is an endpoint, a port, a user and how to authenticate, each written under the resource's own key with a suffix, and this is the reading of those.

func (Fields) Boolean

func (f Fields) Boolean(ctx context.Context, suffix string, fallback bool) (bool, error)

Boolean reads a flag, which is on unless the deployment wrote exactly "false". Deliberately not strconv.ParseBool, so every SDK reads what the deploy engine wrote the same way.

func (Fields) Number

func (f Fields) Number(ctx context.Context, suffix string, fallback int) (int, error)

Number returns a whole number, or the fallback where the deployment recorded none. A value that is not a whole number is an error naming the key.

func (Fields) Optional

func (f Fields) Optional(ctx context.Context, suffix, fallback string) (string, error)

Optional returns a value, or the fallback where the deployment recorded none.

func (Fields) Reader

func (f Fields) Reader() *Reader

Reader reads the same fields and keeps the first failure, so that a caller reading several of them reads them as a list rather than as a check after every one.

One unreadable value makes the whole resource unreachable, so there is nothing to salvage from the rest: a read after a failure is skipped and answers zero, and the caller discards what it gathered along with everything else when it finds the error.

func (Fields) Required

func (f Fields) Required(ctx context.Context, suffix string) (string, error)

Required returns a value the resource cannot be reached without. Absent is an error naming the key, rather than a connection to an empty host.

type Host

type Host interface {
	// ResourceProvider returns the provider an application was given
	// explicitly, and nil when it was given none, which is the ordinary case:
	// the provider is normally the linked one.
	ResourceProvider() Provider
	// Config is what the deployment recorded about the application, which is
	// where a blueprint name is resolved to the identifier the resource was
	// created under. Passed to the provider in a [Ref] rather than read here,
	// so nothing is resolved while handles are being taken.
	Config() *config.Service
	// RecordResourceRef notes that the application reaches a resource, which is
	// reported by the manifest and cross-checked against the static extraction
	// pass.
	RecordResourceRef(kind Kind, name string)
	// ResourceError reports a resource that could not be built. Errors are
	// collected and reported together by celerity.Run rather than returned to
	// each call site, since handles are taken during registration.
	ResourceError(err error)
	// Extracting reports that the process is describing itself for the CLI
	// rather than serving. A missing provider is expected then, since extraction
	// wants the references rather than working clients.
	Extracting() bool
}

Host is the part of an application a resource handle needs.

It is an interface so that this package does not depend on the celerity package; *celerity.App satisfies it.

type Kind

type Kind string

Kind names a resource type, and is the middle segment of a resource reference.

const (
	KindBucket      Kind = "bucket"
	KindQueue       Kind = "queue"
	KindTopic       Kind = "topic"
	KindDatastore   Kind = "datastore"
	KindCache       Kind = "cache"
	KindSQLDatabase Kind = "sqlDatabase"
	KindConfig      Kind = "config"
)

type MissingProviderError

type MissingProviderError struct {
	Kind   Kind
	Name   string
	Linked []string
}

MissingProviderError reports that a resource handle was taken but no provider can build it.

func (*MissingProviderError) Error

func (e *MissingProviderError) Error() string

type Provider

type Provider interface {
	Name() string
	Bucket(Ref) (bucket.Store, error)
	Queue(Ref) (queue.Client, error)
	Topic(Ref) (topic.Client, error)
	Cache(Ref) (cache.Client, error)
	Datastore(Ref) (datastore.Client, error)
	SQLDatabase(Ref) (sqldb.Client, error)
}

Provider builds resource clients for one platform.

It is what a provider module such as resources/aws implements, and it is supplied to the application at startup, so core never imports a cloud SDK.

func DetectedProvider

func DetectedProvider() (Provider, bool)

DetectedProvider returns the provider for the platform this process runs on.

With exactly one linked it is that one, whatever the environment says: a binary carrying only the AWS provider is being run against AWS, including from a developer's machine, where none of the platform's own variables are set.

func FallbackProvider

func FallbackProvider(excluding string) (Provider, bool)

FallbackProvider returns a linked provider other than the one named.

What a provider serving only some of the resource kinds hands the rest to, for example, a development session serves a queue and a topic itself and delegates the other four to the platform's own provider.

Reports false where nothing else is linked, which is a build that asked for a development session without a platform to fall back to.

type Reader

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

Reader gathers field values and the first failure among them.

Built with Fields.Reader.

func (*Reader) Boolean

func (r *Reader) Boolean(ctx context.Context, suffix string, fallback bool) bool

Boolean is Fields.Boolean, and zero once something has failed.

func (*Reader) Err

func (r *Reader) Err() error

Err is the first read that failed, and nil where none did.

func (*Reader) Number

func (r *Reader) Number(ctx context.Context, suffix string, fallback int) int

Number is Fields.Number, and zero once something has failed.

func (*Reader) Optional

func (r *Reader) Optional(ctx context.Context, suffix, fallback string) string

Optional is Fields.Optional, and zero once something has failed.

func (*Reader) Required

func (r *Reader) Required(ctx context.Context, suffix string) string

Required is Fields.Required, and zero once something has failed.

type Ref

type Ref struct {
	// Kind is the resource type, and is checked against the topology rather than
	// trusted: a name belonging to a queue and asked for as a bucket is a
	// mistake in the handler.
	Kind Kind
	// Name is the name the blueprint gave the resource, which is the only name
	// the application knows. What the resource is called once it exists is
	// decided by the deployment.
	Name string
	// Config is what the deployment recorded. This includes which key
	// holds the resource, and the identifiers themselves.
	// Nil only where an application was built
	// without configuration, which is reported as the resource being
	// unresolvable rather than dereferenced.
	Config *config.Service
}

Ref is the blueprint resource a handle was taken for, and how a provider finds out what the deployment actually called it.

A provider is given one of these rather than a name, and nothing is resolved when it is built. The provider holds it and asks it on first use, so a handle taken during registration does not need to make a request to a config store.

func (Ref) Field

func (r Ref) Field(ctx context.Context, suffix string) (string, bool, error)

Field returns one of several values recorded about a resource, by the suffix it was written under.

Most resources are a single identifier, which is Ref.ID. A cache or a database is an endpoint, a port, a user and how to authenticate, and the deploy engine writes each under the resource's own key:

ref.Field(ctx, "_host")

Reports absent rather than failing where the deployment recorded nothing, since most of these have a default and only the provider knows which of them the resource cannot do without.

func (Ref) ID

func (r Ref) ID(ctx context.Context) (string, error)

ID returns the identifier the deployment gave the resource, for example, a bucket's name, a queue's URL, a topic's ARN, a table's name.

func (Ref) String

func (r Ref) String() string

String names the resource by its blueprint name, which is the one a handler asked for and the one an error should point at.