encore

package module
v1.30.0 Latest Latest
Warning

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

Go to latest
Published: Jan 22, 2024 License: MPL-2.0 Imports: 4 Imported by: 2

README

Encore Runtime API

Go Reference Slack MPL-2 License

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIDesc added in v1.5.0

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")
}
Output:

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 added in v1.10.1

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.
	// It is nil if the request is not traced.
	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?

	// 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 TraceData added in v1.12.0

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
}

TraceData describes the trace information for a request.

Directories

Path Synopsis
Package beta contains packages which can be used in Encore applications, however their APIs are not stable and may change in future releases.
Package beta contains packages which can be used in Encore applications, however their APIs are not stable and may change in future releases.
auth
Package auth provides the APIs to get information about the authenticated users.
Package auth provides the APIs to get information about the authenticated users.
errs
Package errs provides structured error handling for Encore applications.
Package errs provides structured error handling for Encore applications.
Package config provides a simple way to access configuration values for a service using the Load function.
Package config provides a simple way to access configuration values for a service using the Load function.
Package cron provides support for cron jobs: recurring tasks that run on a schedule.
Package cron provides support for cron jobs: recurring tasks that run on a schedule.
Package et stands for Encore Tests and provides a number of functions and tools for writing fully integrated test suites for Encore applications.
Package et stands for Encore Tests and provides a number of functions and tools for writing fully integrated test suites for Encore applications.
Package middleware provides middleware functionality for defining generic processing across multiple API endpoints, typically for cross-cutting concerns like validation, caching, or error monitoring.
Package middleware provides middleware functionality for defining generic processing across multiple API endpoints, typically for cross-cutting concerns like validation, caching, or error monitoring.
Package pubsub provides Encore applications with the ability to create Pub/Sub Topics and multiple Subscriptions on those topics in a cloud-agnostic manner.
Package pubsub provides Encore applications with the ability to create Pub/Sub Topics and multiple Subscriptions on those topics in a cloud-agnostic manner.
Package rlog provides a simple logging interface which is integrated with Encore's inbuilt distributed tracing.
Package rlog provides a simple logging interface which is integrated with Encore's inbuilt distributed tracing.
storage
cache
Package cache provides the ability to define distributed Redis cache clusters and functionality to use them in a fully type-safe manner.
Package cache provides the ability to define distributed Redis cache clusters and functionality to use them in a fully type-safe manner.
sqldb
Package sqldb provides Encore services direct access to their databases.
Package sqldb provides Encore services direct access to their databases.
sqldb/sqlerr
Package sqlerr provides a set of common error codes for SQL datbaases.
Package sqlerr provides a set of common error codes for SQL datbaases.
types
uuid
Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122 and DCE 1.1.
Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122 and DCE 1.1.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL