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 PathParam
• type PathParams
  • func (PathParams) Get(name string) string
• type Request
  • func CurrentRequest() *Request
• type RequestType

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
}

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`.
	EnvLocal EnvironmentType = "local"
)

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

	// 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?

	// 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
}

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
)