encore

README

Encore – The Backend Development Engine

Encore Runtime API

This repository contains the Encore's Runtime API contract, which Encore applications are built against.

go get -u encore.dev

When compiling your application the encore compiler will automatically provide an implementation of this API. The default implementation can be found here.

Documentation

Overview

Package encore provides the runtime API contract, which Encore applications are build against.

Encore – The Backend Development Engine

https://encore.dev

Encore makes it incredibly simple to create distributed systems, backend services and APIs. While still deploying to your own cloud account, Encore helps you escape the maze of cloud complexity:

- No endless repetition of boilerplate.

- No infrastructure to worry about.

- No reinventing the wheel.

Start building with a fantastic flow state experience that unlocks your creative potential. All of this is freely available, based on the Open Source Encore Go Framework.

For more information visit the website https://encore.dev or the documentation at https://encore.dev/docs.

Package encore

This package provides the APIs for getting AppMetadata about the current application and the CurrentRequest. For more information see https://encore.dev/docs/develop/metadata.

Index

• type APIDesc
• type AppMetadata
  • func Meta() (_ *AppMetadata)
• type BuildMeta
• type CloudProvider
• type DeployMeta
• type EnvironmentMeta
• type EnvironmentType
• type MessageData
• type PathParam
• type PathParams
  • func (PathParams) Get(name string) (_ string)
• type Request
  • func CurrentRequest() (_ *Request)
• type RequestType
• type Tags
  • func (Tags) Has(tag string) (_ bool)
• type TraceData

Examples

• CurrentRequest
• Meta

Types

type APIDesc

type APIDesc struct {
	// RequestType specifies the type of the request payload,
	// or nil if the endpoint has no request payload or is Raw.
	RequestType reflect.Type

	// ResponseType specifies the type of the response payload,
	// or nil if the endpoint has no response payload or is Raw.
	ResponseType reflect.Type

	// Raw specifies whether the endpoint is a Raw endpoint.
	Raw bool

	// Tags describes what tags are attached to the endpoint.
	Tags Tags
}

APIDesc describes the API endpoint being called.

type AppMetadata

type AppMetadata struct {
	// The application ID, if the application is not linked to the Encore platform this will be an empty string.
	//
	// To link to the Encore platform run `encore app link` from your terminal in the root directory of the Encore app.
	AppID string

	// The base URL which can be used to call the API of this running application.
	//
	// For local development it is "http://localhost:<port>", typically "http://localhost:4000".
	//
	// If a custom domain is used for this environment it is returned here, but note that
	// changes only take effect at the time of deployment while custom domains can be updated at any time.
	APIBaseURL url.URL

	// Information about the environment the app is running in.
	Environment EnvironmentMeta

	// Information about the running binary itself.
	Build BuildMeta

	// Information about this deployment of the binary
	Deploy DeployMeta
}

AppMetadata contains metadata about the running Encore application.

func Meta

func Meta() (_ *AppMetadata)

Meta returns metadata about the running application.

Meta will never return nil.

Example

Change the implementation of some code based on which cloud provider is being used.

switch encore.Meta().Environment.Cloud {
case encore.CloudAWS:
	client = NewRedshiftClient()
case encore.CloudGCP:
	client = NewBigQueryClient()
case encore.CloudLocal:
	client = LocalFileWriter("/tmp/app-writes.txt")
default:
	panic("unsupported cloud provider")
}

type BuildMeta

type BuildMeta struct {
	// The git commit that formed the base of this build.
	Revision string

	// true if there were uncommitted changes on top of the Commit.
	UncommittedChanges bool
}

type CloudProvider

type CloudProvider string

CloudProvider represents the cloud provider this application is running in.

For more information about how Cloud Providers work with Encore, see https://encore.dev/docs/deploy/own-cloud

Additional cloud providers may be added in the future.

const (
	CloudAWS   CloudProvider = "aws"
	CloudGCP   CloudProvider = "gcp"
	CloudAzure CloudProvider = "azure"

	// EncoreCloud is Encore's own cloud offering, and the default provider for new Environments.
	EncoreCloud CloudProvider = "encore"

	// CloudLocal is used when an application is running from the Encore CLI by using either
	// 'encore run' or 'encore test'
	CloudLocal CloudProvider = "local"
)

type DeployMeta

type DeployMeta struct {
	// The deployment ID created by the Encore Platform.
	ID string

	// The time the Encore Platform deployed this build to the environment.
	Time time.Time
}

type EnvironmentMeta

type EnvironmentMeta struct {
	// The name of environment that this application.
	// For local development it is "local".
	Name string

	// The type of environment is this application running in
	// For local development this will be EnvLocal
	Type EnvironmentType

	// The cloud that this environment is running on
	// For local development this is CloudLocal
	Cloud CloudProvider
}

type EnvironmentType

type EnvironmentType string

EnvironmentType represents the type of environment.

For more information on environment types see https://encore.dev/docs/deploy/environments#environment-types

Additional environment types may be added in the future.

const (
	// EnvProduction represents a production environment.
	EnvProduction EnvironmentType = "production"

	// EnvDevelopment represents a long-lived cloud-hosted, non-production environment, such as test environments.
	EnvDevelopment EnvironmentType = "development"

	// EnvEphemeral represents short-lived cloud-hosted, non-production environments, such as preview environments
	// that only exist while a particular pull request is open.
	EnvEphemeral EnvironmentType = "ephemeral"

	// EnvLocal represents the local development environment when using 'encore run' or `encore test`.
	//
	// Deprecated: EnvLocal is deprecated and Encore will no longer return this value. A locally running environment
	// can be identified by the combination of EnvDevelopment && CloudLocal. This constant will be removed in a future
	// version of Encore.
	EnvLocal EnvironmentType = "local"

	// EnvTest represents a running unit test
	EnvTest EnvironmentType = "test"
)

type MessageData

type MessageData struct {
	// Service is the name of the service with the subscription.
	Service string

	// Topic is the name of the topic the message was published to.
	Topic string

	// Subscription is the name of the subscription the message was received on.
	Subscription string

	// ID is the unique ID of the message assigned by the messaging service.
	// It is the same value returned by topic.Publish() and is the same
	// across delivery attempts.
	ID string

	// Published is the time the message was first published.
	Published time.Time

	// DeliveryAttempt is a counter for how many times the messages
	// has been attempted to be delivered.
	DeliveryAttempt int
}

MessageData describes the request data for a Pub/Sub message.

type PathParam

type PathParam struct {
	Name  string // the name of the path parameter, without leading ':' or '*'.
	Value string // the parsed path parameter value.
}

PathParam represents a parsed path parameter.

type PathParams

type PathParams []PathParam

PathParams contains the path parameters parsed from the request path. The ordering of the parameters in the path will be maintained from the URL.

func (PathParams) Get

func (PathParams) Get(name string) (_ string)

Get returns the value of the path parameter with the given name. If no such parameter exists it reports "".

type Request

type Request struct {
	Type    RequestType // What caused this request to start
	Started time.Time   // What time the trigger occurred

	// Trace contains the trace information for the current request.
	Trace *TraceData

	// APICall specific parameters.
	// These will be empty for operations with a type not APICall
	API        *APIDesc   // Metadata about the API endpoint being called
	Service    string     // Which service is processing this request
	Endpoint   string     // Which API endpoint is being called
	Path       string     // What was the path made to the API server
	PathParams PathParams // If there are path parameters, what are they?
	Method     string     // What HTTP method was used

	// Headers contains the request headers sent with the request, if any.
	//
	// It is currently empty for service-to-service API calls when the caller
	// and callee are both running within the same process.
	// This behavior may change in the future.
	Headers http.Header

	// PubSubMessage specific parameters.
	// Message contains information about the PubSub message,
	Message *MessageData

	// Payload is the decoded request payload or Pub/Sub message payload,
	// or nil if the API endpoint has no request payload or the endpoint is raw.
	Payload any

	// CronIdempotencyKey contains a unique id for a particular cron job execution
	// if this request was triggered by a Cron Job.
	//
	// It can be used to uniquely identify a particular Cron Job execution event,
	// and also serves as a way to distinguish between Cron Job-triggered requests
	// and other requests.
	//
	// If the request was not triggered by a Cron Job the value is the empty string.
	CronIdempotencyKey string
}

Request provides metadata about how and why the currently running code was started.

The current request can be returned by calling CurrentRequest()

func CurrentRequest

func CurrentRequest() (_ *Request)

CurrentRequest returns the Request that is currently being handled by the calling goroutine

It is safe for concurrent use and will return a new Request on each evocation, so can be mutated by the calling code without impacting future calls.

CurrentRequest never returns nil.

Example

req := encore.CurrentRequest()
elapsed := time.Since(req.Started)

if req.Type == encore.APICall {
	fmt.Printf("%s.%s has been running for %.3f seconds", req.Service, req.Endpoint, elapsed.Seconds())
}

Output:

myservice.api has been running for 0.543 seconds

type RequestType

type RequestType string

RequestType describes how the currently running code was triggered

const (
	None          RequestType = "none"           // There was no external trigger which caused this code to run. Most likely it was triggered by a package level init function.
	APICall       RequestType = "api-call"       // The code was triggered via an API call to a service
	PubSubMessage RequestType = "pubsub-message" // The code was triggered by a PubSub subscriber
)

type Tags

type Tags []string

Tags describes a set of tags an endpoint is tagged with, without the "tag:" prefix.

The ordering is unspecified.

func (Tags) Has

func (Tags) Has(tag string) (_ bool)

Has reports whether the set contains the given tag. The provided value should not contain the "tag:" prefix.

type TraceData

type TraceData struct {
	TraceID          string
	SpanID           string
	ParentTraceID    string // empty if no parent trace
	ParentSpanID     string // empty if no parent span
	ExtCorrelationID string // empty if no correlation id
	Recorded         bool   // true if this trace is being recorded
}

TraceData describes the trace information for a request.