resources

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 18 Imported by: 10

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

View Source 
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.

View Source 
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.

View Source 
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.

Variables

This section is empty.

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.

Source Files

View all Source files

Directories

Path Synopsis
aws module
The bucket package is the provider-agnostic interface to object storage: S3, Cloud Storage, Azure Blob Storage.
 The bucket package is the provider-agnostic interface to object storage: S3, Cloud Storage, Azure Blob Storage.
The cache package contains the provider-agnostic interface to a key-value cache: ElastiCache, Memorystore, Azure Cache, and the Valkey instance a local development session runs.
 The cache package contains the provider-agnostic interface to a key-value cache: ElastiCache, Memorystore, Azure Cache, and the Valkey instance a local development session runs.
Package datastore is the provider-agnostic interface to a NoSQL document store: DynamoDB, Firestore, Cosmos DB, and the engines a self-hosted deployment runs.
 Package datastore is the provider-agnostic interface to a NoSQL document store: DynamoDB, Firestore, Cosmos DB, and the engines a self-hosted deployment runs.
local module
The queue package contains the provider-agnostic interface to a point-to-point queue: SQS, Cloud Tasks, Service Bus.
 The queue package contains the provider-agnostic interface to a point-to-point queue: SQS, Cloud Tasks, Service Bus.
redis module
otel module
Package sqldb is the provider-agnostic interface to a relational database: RDS, Cloud SQL, Azure Database.
 Package sqldb is the provider-agnostic interface to a relational database: RDS, Cloud SQL, Azure Database.
otel module
Package topic is the provider-agnostic interface to publish-subscribe: SNS, Pub/Sub, Service Bus Topics.
 Package topic is the provider-agnostic interface to publish-subscribe: SNS, Pub/Sub, Service Bus Topics.

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.