Encore Flow is the world's first intelligent visual backend architecture tool for the cloud. Flow helps you improve your microservices architecture, and makes it easy for everyone on the team to understand it. It lets you instantly identify which services depend on each other and how they work together. With Flow, building backends has never been easier – from designing your architecture and collaborating on pull requests, to onboarding new team members.

Flow is now available for all Encore users! If you haven’t tried Encore yet, get started here.

🥐 If you already have Encore installed, run encore version update to upgrade.

Flow Key Features

• Flow gives your entire team an accurate and up-to-date view of your entire system – point and click in all parts of your microservices architecture to instantly reveal how it’s wired.
• Flow gives you a real-time view of the changes you’re making as you code, and will soon integrate with GitHub to automatically add visual context to every pull request.
• Use Flow to follow API calls across services and visualize dependencies, to track down bottlenecks before they grow into big problems

Read more about Encore Flow in the docs.

Over the coming months we’ll extend Encore Flow with a suite of intelligent development tools, to make it even simpler to build your cloud backend. Follow us on Twitter or Star Encore on GitHub to stay up to date.

Azure Pub/Sub

Encore Pub/Sub now officially supports Azure, bringing the support to all the major cloud providers! Give it a spin and let us know what you think.

Bug fixes and other improvements

• Encore now runs Go 1.19.1
• Encore now provisions Cloud SQL instances with PostgreSQL 14
• Fixed provisioning of Pub/Sub topics without subscribers

What's next

Over the coming weeks we'll be adding support for configuration, caching, Kubernetes deployments, and more. Vote on your favorite feature on the roadmap!

If you like what we're up to, why not star Encore here on GitHub?

As always, if you have questions or feedback, tell us on Discord or just reply to this email.

We're excited to hear your feedback! ❤️

Catch you in the cloud,

The Encore Team

We're excited to share Encore's world-class developer experience now extends to asynchronous event processing with the addition of Encore PubSub!

Pub/Sub is one of the core building blocks of modern distributed systems. This means you can now easily:

• Effortlessly build event driven backend applications
• Off-load expensive business logic into the background and not during request processing
• Process queues of work in a reliable, scalable, and cloud-agnostic way
• Decouple systems from each other

Building such applications typically involves endless repetition and tedious boilerplate. No more.

Run encore version update to grab the latest version and experience it for yourself!

— If you're new to Encore, check out the Quick Start Guide to get started building.

Encore PubSub

Encore PubSub takes the same approach to building distributed systems as the rest of Encore, and makes building event-driven, asynchronous a breeze. With Encore you define your topics and subscriptions directly in your backend code, like any other object.

With just a few lines of code we have a serverless backend that scales from zero to hundreds of millions of users, with zero boilerplate and with static type safety. Encore takes care of all the complex, boring parts, so you can focus on building your product:

• Provisioning and configuring the necessary cloud infrastructure
• Connecting it all together, generating all the boilerplate code and configuration to use the infrastructure within your backend application
• Connecting it all together with distributed tracing for effortless observability

The best part of all? It works the same way for local development as well as the major cloud providers. Encore provisions the cloud native infrastructure component for your specific cloud provider of choice, but the code works the same way.

To define a topic and begin publishing messages is just a handful lines of code:

import "encore.dev/pubsub"

type SignupEvent struct {
    Username string
    Email    string
}

var Signups = pubsub.NewTopic[*SignupEvent]("user-signups", pubsub.TopicConfig{
    DeliveryGuarantee: pubsub.AtLeastOnce,
})

// To publish a message:
_, err := Signups.Publish(ctx, &SignupEvent{Username: "jane.doe", Email: "[email protected]"})

To begin receiving messages is equally simple:

import "encore.dev/pubsub"

var _ = pubsub.NewSubscription(
    user.Signups, "send-welcome-email",
    pubsub.SubscriptionConfig[*user.SignupEvent] {
        Handler: SendWelcomeEmail,
    },
)

func SendWelcomeEmail(ctx context.Context, event *user.SignupEvent) error {
    // .. send email ...
}

We're excited to share Encore's world-class developer experience now extends to asynchronous event processing with the addition of Encore PubSub!

Pub/Sub is one of the core building blocks of modern distributed systems. This means you can now easily:

• Effortlessly build event driven backend applications
• Off-load expensive business logic into the background and not during request processing
• Process queues of work in a reliable, scalable, and cloud-agnostic way
• Decouple systems from each other

Building such applications typically involves endless repetition and tedious boilerplate. No more.

Run encore version update to grab the latest version and experience it for yourself!

— If you're new to Encore, check out the Quick Start Guide to get started building.

Encore PubSub

Encore PubSub takes the same approach to building distributed systems as the rest of Encore, and makes building event-driven, asynchronous a breeze. With Encore you define your topics and subscriptions directly in your backend code, like any other object.

With just a few lines of code we have a serverless backend that scales from zero to hundreds of millions of users, with zero boilerplate and with static type safety. Encore takes care of all the complex, boring parts, so you can focus on building your product:

• Provisioning and configuring the necessary cloud infrastructure
• Connecting it all together, generating all the boilerplate code and configuration to use the infrastructure within your backend application
• Connecting it all together with distributed tracing for effortless observability

The best part of all? It works the same way for local development as well as the major cloud providers. Encore provisions the cloud native infrastructure component for your specific cloud provider of choice, but the code works the same way.

To define a topic and begin publishing messages is just a handful lines of code:

import "encore.dev/pubsub"

type SignupEvent struct {
    Username string
    Email    string
}

var Signups = pubsub.NewTopic[*SignupEvent]("user-signups", pubsub.TopicConfig{
    DeliveryGuarantee: pubsub.AtLeastOnce,
})

// To publish a message:
_, err := Signups.Publish(ctx, &SignupEvent{Username: "jane.doe", Email: "[email protected]"})

To begin receiving messages is equally simple:

import "encore.dev/pubsub"

var _ = pubsub.NewSubscription(
    user.Signups, "send-welcome-email",
    pubsub.SubscriptionConfig[*user.SignupEvent] {
        Handler: SendWelcomeEmail,
    },
)

func SendWelcomeEmail(ctx context.Context, event *user.SignupEvent) error {
    // .. send email ...
}

Testing PubSub

To complement the new PubSub support Encore now comes with a new et (encore testing) package to simplify testing distributed systems.

We're starting with support for testing PubSub behavior, but over time we plan to expand on it to support easy testing of various distributed system behaviors. Read the package docs for more information.

Bug fixes and other improvements

• Improved handling of max connections for local development (#300)
• Improved keep-alive of encore db shell database sessions (#263)
• Improved error messages for several common Encore syntax errors
• Added support for customizing GOARCH and the docker base image for encore eject docker (#269)
• Improved CORS handling for local development (#276, #278, #286)
• Fixed running encore run before encore auth login on new systems (#299)
• Fixed rendering of encore.dev/rlog log output when using structured logging of booleans (#308)

Thanks to all our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. Big thanks to @davidmytton, @bscott, @bjaanes and others for your bug reports and feedback!

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Discord to see what's going on, learn from others, and share what you're working on.

What’s next

Over the coming weeks we'll be adding much requested flexibility to the Encore framework, with improved support for things like: middleware, configuration and dependency injection. Vote on your favorite feature on the roadmap – If you like what's going on, why not give the project a star?

As always, if you have questions or ideas, come tell us on Discord. We’re excited to hear your feedback! ❤️

Catch you in the cloud, The Encore Team

We're hard at work adding much requested flexibility to the Encore framework. In this week's release, we've added native support for HTTP headers in Encore APIs and authentication handlers. No more having to use only JSON!

This means you can now easily:

• Model REST APIs like you're used to
• Return HTTP headers
• Use the Local Development Dashboard to see how each field will be encoded

Run encore version update to grab the latest version and experience it for yourself! – If you're new to Encore, check out the Quick Start Guide to get started building.

Improved authentication support

Encore now supports a more flexible way to express authentication handlers, using struct payloads in the same way you're used to for regular endpoints. The struct payloads can include multiple fields that can be sourced from either HTTP Headers or query strings.

That means you can do things like:

• Implement more advanced authentication methods that go beyond simple Bearer tokens
• Accept client_id as a query string and an API key in the Authorization header, at the same time
• Support HTTP Basic Authentication

Improved client code generation

The Encore client code generation has received a major upgrade for both TypeScript and Go clients.

• Support for HTTP headers
• Support for structured authentication handlers
• API errors are now reported as structured errors rather than strings
• The TypeScript client now properly supports raw endpoints, including specifying the request body, HTTP method, and arbitrary fetch options

Note: The Go client now validates the provided HTTP method for calling raw endpoints. In the rare case that a raw endpoint was called without a valid Method, the behavior of the new client generator will differ by returning an error. In previous versions it instead defaulted to making a GET request.

Bug fixes and other improvements

• Forward slashes encoded as %2F within string path segments no longer causes that path segment to be treated as two separate segments.
• In the rare case that path segment parameters conflict with reserved keywords or names the generated names are now prefixed with _ to avoid name collisions.
• Blank or missing auth tokens in generated TypeScript clients will no longer be sent in the Authorization header
• The encore.Meta function now reports the correct value for the APIBaseURL field for local development (#245)
• Encore now supports ejecting an application as a standalone docker container. See encore eject docker --help for more information.
• A more helpful error message is now displayed when an environment cannot be found when generating a client (#118)

Thanks to all our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. Big thanks to @ValeriaVG, @Qolzam, Prasanna Balaji, @vilhelmmelkstam, and @MaxDanielsson for your bug reports and feedback!

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Discord to see what's going on, learn from others, and share what you're working on.

What’s next

Over the coming weeks we'll be adding much requested flexibility to the Encore framework, with improved support for things like: middleware, configuration and dependency injection. Vote on your favorite feature on the roadmap

As always, if you have questions or ideas, come tell us on Discord. We’re excited to hear your feedback! ❤️

Catch you in the cloud,
André & the Encore team

Not only is it now a nicer place to rest your eyes, we've also fixed lots of bugs and removed many points of confusion.

The big star of this update is our very own off-white color, which we hope will give even the fiercest dark-mode fans a reason to stay on the light side. Still want dark mode? Tell us on Discord.

There's also some shiny new functionality

• Traces can now be filtered on services, endpoints and errors.
• We've overhauled the tracing backend to dramatically improve performance, we estimate page load is up to 100x faster!
• The overview page gives you easy access to the latest Encore release notes and tutorials.

Log in to experience it for yourself!

Thanks to our community contributors!

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. Thanks to Riccardo Re, Mokhtar Bacha, ValeriaVG, Vilhelm Melkstam, and MaxD for your bug reports and feedback!

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Discord to see what's going on, learn from others, and share what you're working on.

What's next

Over the coming weeks we'll be adding much requested flexibility to the Encore framework, with improved support for things like: http headers in Encore APIs, middleware, and dependency injection.

As always, if you have questions or feedback, tell us on Discord.

Catch you in the cloud,
The Encore team

As developers, we often find ourselves in situations where we need to change something in our codebase, but don't want to change it everywhere the code is deployed.

Using Encore's new App Metadata API, you can now query the runtime to find out what environment the application is running in. Which means you can easily load the appropriate configuration files into memory and get the correct behavior for each environment.

This makes it a breeze to do things like:

• Use different cloud services per environment
• Define environment specific business logic

Check out the docs to learn more.

Upgrading

With this release, we've updated the runtime API with the new metadata API's and types. To upgrade you will need to both:

• Run encore version update to download v1.1.0 of the Encore compiler.
• In each of your Encore applications, you will also need to run go get -u encore.dev to upgrade to the latest runtime API.

Bugfixes and other improvements

• We've made a ton of improvements to Encore's SQLDB handling! Including upgrading to PostgreSQL 14, and adding support for external DB clusters for CI/CD.
• The Encore runtime now shuts down with grace.
• Encore now runs on Go 1.18.2.
• In case you've missed it, we've launched a new visual identity and have given the website a lot of love!
• ...and much more.

— Thanks to @davidmytton, @klemmster, @ValeriaVG, @vilhelmmelkstam, @kwihl, and @MaxDanielsson for your contributions, bug reports, and feedback!

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Discord to see what's going on, learn from others, and share what you're working on.

What's next

Over the coming weeks we'll be releasing a vastly improved web UI, and focus on adding much requested flexibility to the Encore framework. We'll add improved support for things like: http headers in Encore APIs, middleware, and dependency injection.

As always, if you have questions or feedback, tell us on Discord or just reply to this email.

We're excited to hear your feedback! ❤️

Catch you in the cloud,
The Encore team

We're incredibly excited to announce Encore v1.0. With this release, Encore is fully prepared to support you in your next creative endeavour.

It's our belief that Encore will transform developers' lives. Our work will become far more joyful and creative. Rather than it being 80% about configuring tools and services that have been reconfigured thousands of times before, we'll spend our days building new products that have a real impact. And that could have huge benefits for society. Imagine the exciting innovations if the world's 25+ million developers are freed up to be five times more productive!

We hope that Encore will open things up to a broader range of folk. You won't need to have a deep understanding of the nuances of cloud services to develop world-changing software that is available on a global scale. Now more people who are passionate about real-world issues which they're trying to solve will be empowered to have an incredible impact.

Highlights of what's been added in this release

AWS Cloud deployments now generally available

We're happy to announce that we've added full support for deploying your Encore applications to Amazon Web Services. This is a huge milestone, as Encore now supports deploying seamlessly to all major cloud providers.

If you wish, you can easily deploy your application to all of them, for those multi-cloud bragging rights. With Encore it's as easy as connecting your cloud account. There's no second step.

Check out the docs to learn how to connect your Encore app to your AWS account and start deploying in minutes.

Speedier builds and structured logs

When you deploy your Encore application, it takes care of building your app, provisioning the necessary infrastructure, and orchestrating the deployment. With this release, we've made builds blazing fast and laid the foundation for better and more structured build logs. Behind the scenes we've ripped out GCP Cloud Build and replaced it with our own firecracker based builder. If this tickles your fancy, we're busy writing an in-depth article on this very topic. Watch this space for more details.

Improvements & Bugfixes

• We've upgraded the Encore fork of the Go runtime to 1.18.1 (it's now 0.0.1 better than before)

We're excited to hear your feedback!

Catch you in the cloud, The Encore Team

Deploy your Encore application to Microsoft Azure

One of the core beliefs behind Encore is that developers shouldn't need to worry about the intricacies of cloud infrastructure. Instead you should focus on being creative and crafting unique software for your users.

To achieve this, Encore enables you to deploy your applications to any supported clouds (yes plural), without making code changes. We're super excited to announce we've now added full support for Microsoft Azure to the list!

Float into the flow with Azure:

• Create a new environment and deploy your app to Azure in minutes.
• Keep using all Encore features in exactly the same way as before!
• Run multiple environments across Azure / GCP / Encore for the same app. (AWS dropping soon!)

Check out the docs to learn more.

Bugfixes and other improvements

• Added support for line based comments on struct fields.

— Thanks to Javi Alvarez, Valeria Viana Gusmao, Denis Denis, Vilhelm Melkstam, Max D, Alessandro Resta and Richard Palm for your contributions and bug reports. (WOW, what a long list, and what a great community!)

Join the most pioneering developer community

Developers building with Encore are forward thinkers working on interesting and exciting projects. Join the conversation on Discord to see what's going on, and share what you're working on.

What's next

Over the coming weeks we'll be adding AWS to the mix, dropping a huge UI update, and get on with adding native support for Queues and Object storage.

– Remember, you can share your comments and ideas on our Public Roadmap.

As always, if you have questions or feedback, join us on Discord or just reply to this email.

We're excited to hear your feedback!

Catch you in the cloud,

André (Founder) & the Encore team

We're continuously refining the Encore experience to make it even more frictionless, and give you more control and flexibility. This week we've released a bunch of big improvements to how deployments work for all your Encore applications.

Highlights of what we shipped the past week:

• Much improved overview – Builds, infrastructure changes, and deploys in one view.
• No surprises in your cloud bills – You can now choose whether you want to manually approve any infrastructure changes for each environment.
• You can now easily re-trigger deploys from the Cloud Dashboard.

Bugfixes and other improvements

• We refined the internal alerting and monitoring for the Cloud Dashboard to ensure availability.
• We fixed a subtle bug related to parsing errors in app log messages. – Thanks to Valeria Viana Gusmao, Dinesh Katwal, and Glenn Lewis for their bug reports and contributions!

Join the most pioneering developer community

Developers building with Encore are forward thinkers working on interesting and exciting projects. Join the conversation on Discord to see what's going on, and share what you're working on.

What’s next

Over the coming weeks we’ll be reactivating AWS and Azure support for all Encore users, releasing a polished version of the Cloud Dashboard, adding native support for queues and object storage, and much more. – Remember, you can share your comments and ideas on our Public Roadmap.

As always, if you have questions or feedback, join us on discord.

We're excited to hear your feedback!

Keep building,

André (Founder) & the Encore team

Bring Your Own Domain Names

You asked for it, and so it's here! We've just released Custom Domains, which lets you serve your Encore powered backend API's from your own domains. No proxy, no certificates, and no hassle!

The best part? No need to update your CLI tools, just head to the Cloud Dashboard and try it out yourself!

Check out the docs to learn more.

PR Environments just got even better

One of the lesser known — but very powerful — features of Encore just got even better!

In case you didn't know: When you've linked your app with GitHub, Encore will automatically provision dedicated Preview Environments for each pull request. (See how in the docs)

PR environments work just like regular development environments, and lets you test your changes before merging. This week, we made PR environments even better, and added full support for Encore's native Cron Jobs!

Improvements & Bugfixes

• We've added support for GitHub login to make things even smoother.
• We upgraded the platform to Go 1.17.8, and are standing ready for the release of 1.18.

— Thanks to @MaxDanielsson, @VilhelmMelkstam, and @gmlewis for giving us feedback!

Join the most pioneering developer community

Developers building with Encore are forward thinkers working on interesting and exciting projects. Join the conversation on Discord to see what's going on, and share what you're working on.

What's next

Over the coming weeks we'll be improving the Deployment UX, give you more knobs in the Distributed Tracing dashboard, add native support for Object Storage, and much more!

— Remember, you can share your comments and ideas on our Public Roadmap.

We're excited to hear your feedback!

Keep building, André (Founder) & the Encore team

When building backend applications you often need to run periodic and recurring tasks. For example, to send a welcome email to everyone who signed up recently. Encore provides native support for these types of use cases using Cron Jobs. Here's how easy it is:

import "encore.dev/cron"

// Send a welcome email to everyone who signed up in the last two hours.
var _ = cron.NewJob("welcome-email", cron.JobConfig{
    Title:    "Send welcome emails",
    Every:    2 * cron.Hour,
    Endpoint: SendWelcomeEmail,
})

That's it! When this is deployed, Encore will call the SendWelcomeEmail endpoint (not pictured) every 2 hours. There is no need to maintain any infrastructure; Encore itself takes care of the scheduling, monitoring and execution. Hooray!

What's more, Encore's Cloud Dashboard has a shiny new Cron Jobs dashboard to help you keep track of all your jobs. Check it out:

This means you can now schedule recurring tasks without worrying about:

• How yet another configuration language works –– it's just plain Go.
• Setting up and maintaining servers or third-party services –– it's all handled by Encore.
• Keeping track of what jobs are running in each environment – just check the dashboard!

To get started, install the latest Encore release with encore version update and upgrade your application's dependency with go get encore.dev@latest.

Check out the docs to learn more.

Bugfixes and other improvements

• Added support for code coverage with encore test -cover (#144)
• Improved documentation on using external databases
• Improved documentation on handling database migration errors
• Improved documentation on how to use GCP (#102)
• Fixed encore test mistakenly requiring Docker when the app has no database (#98)

Thanks to @ValeriaVG and @wisdommatt for the contributions!

What’s next

Over the coming weeks we’ll be adding several powerful features to help you build your backend. Soon we’re adding native support for Custom API Domains, Object Storage (S3), Pub/Sub, and more! – Remember, you can share your comments and ideas on our Public Roadmap.

As always, if you have questions or feedback, join us on Discord or just reply to this email. We’re excited to hear your feedback! ❤️

Happy 2022! (We're a bit late to the party, we know...) We’ve been heads down improving our platform and are super excited to finally announce these product updates.

We’ve just shipped some huge improvements to make your applications faster, and ensure our service is more reliable as you’re developing.

Encore now offers full support for Google Cloud Run, adding an even easier and cheaper way to deploy to your own cloud account. Perfect for getting your next idea up and running quickly.

We’ve also integrated with Cloudflare, giving you the full power of their edge network, for even lower latency and higher performance. This works transparently across all the cloud providers we support, including Encore Cloud.

Auth Keys

Sometimes it’s practical to use the Encore CLI in an automated fashion, for instance to automatically run tests in a CI/CD pipeline beyond what Encore already provides. That was trickier than it should have been, since the CLI required interactive login. But no longer!

We now support pre-authenticated keys that grant a machine user access to a single Encore application, perfect for your CI environments and other automated tools. — Read more about auth keys in the docs.

Password-based & Social Login

Logging in with one-time codes over email can be annoying because you can’t use your password manager. We hear you! That’s why we’re happy to announce we’ve now rolled out password-based login and social login. — Next time you log in you’ll need to set a password using “Reset password” on the login screen, using the same email address as before.

What’s next

Over the next fews weeks we’ll be adding lots more powerful features to help you build your next great product faster. Soon we’re adding native support for Cron Jobs, Custom API Domains, Object Storage (S3), Pub/Sub, and more. — Remember, you can share your comments and ideas on our Public Roadmap.

That’s it for this time! As always, if you have questions or feedback, join us on Discord. We’re excited to hear your feedback.

We're excited to announce Encore v0.17, our most feature-packed and best release yet!

If you'd like to give Encore a go for the first time, check out our quick start. If you already have Encore installed, you can update with encore version update.

The simplest way to build a REST API

We've heard you: the Encore developer experience is great, but building REST APIs was too cumbersome. No more! You can now define REST APIs with incredible speed and productivity, through the power of Encore's static analysis and code generation engine. Just take a look:

// The List endpoint returns a list of blog articles.
// It can be called simply as:
//
//     GET /blog?limit=30&offset=0
//
//encore:api public method=GET path=/blog
func List(ctx context.Context, p *ListParams) (*ListResponse, error) {
    // Fetch results...
}

// ListParams are the query parameters for the List endpoint.
type ListParams struct {
    Limit int
    Offset int
}

// ListResponse is the response schema for the List endpoint.
type ListResponse struct {
    Posts []*Post
}

If it looks just like regular, plain Go code, you'd be exactly right! Since it's a GET endpoint, Encore automatically parses the ListParams fields and parses them from the query string in the HTTP request.

This approach lets you think and develop your API in terms of functions and data structures, instead of worrying about low-level HTTP request parsing. The end result is a remarkably simple programming paradigm that dramatically increases productivity.

We call it the Encore Application Model — a combination of static analysis and code generation — and it's all about understanding what you're trying to do and helps you achieve it faster and easier than ever before. By taking all the boilerplate out of backend development we're left with a much more enjoyable developer experience as well.

ORM Support and Query Helpers

Encore's SQL Database support now works seamlessly with the large Go ecosystem of ORMs and query helpers! This means if you want to use tools like:

• github.com/Masterminds/squirrel
• github.com/kyleconroy/git-remote-encore.exe
• github.com/jmoiron/sqlx

... and so on, you can! In your Encore service, use the new sqldb.Named function to get a database object, and then use its Stdlib method to get a *sql.DB object that you can integrate with any of these packages as you see fit.

package foo

// db is a *sql.DB that is automatically connected
// to the database belonging to the "foo" service.
//
// Like always with Encore, you don't need to worry
// about provisioning, database passwords, or having
// to set up schema migrations. It's all taken care of.
var db = sqldb.Named("foo").Stdlib()

Testing auth endpoints

If you're building an application with Encore's built-in authentication support, you're in luck! Testing endpoints that required authentication is now much easier than before, with the introduction of auth.WithContext:

import "encore.dev/beta/auth"

func TestAuthEndpoint(t *testing.T) {
    ctx = auth.WithContext(context.Background(), "some-user-id", &AuthData{})
    err := MyAuthEndpoint(ctx)
    // ...
}

//encore:api auth
func MyAuthEndpoint(ctx context.Context) error {
    // ....
}

This functionality is actually not limited to testing, and can be used anywhere, including in your business logic for cases where you need to make an API call on behalf of an authenticated user.

Bugfixes and other improvements

We also made lots of smaller improvements and bugfixes:

• Added --port and --listen options to encore run to change listen port/address (#94)
• Overhauled code generation for increased performance and maintainability
• Fixed database request tracking in tests (#89)
• Fixed a bug where the Dev Dashboard sometimes didn't show the latest result (#53)
• Fixed return type mismatch between Encore runtime and client library (#55)
• Fixed using unicode in API Explorer (#97)

We're looking forward to seeing what you build! Join us on Discord to participate in the growing community of Encore developers, and stay tuned for more updates soon!

Encore now has much improved documentation, and an improved encore run experience!

Revamped Documentation

• Reworked documentation site from the ground up
• Open sourced docs so anybody can contribute to better docs
• Added documentation search
• Improved CONTRIBUTING.md instructions

Improved encore run experience

We added more real-time feedback about what Encore is doing when starting up. This especially helps when starting to use Encore and there's lots of things happening (compiling the Go standard library and all app dependencies, pulling docker images for PostgreSQL, creating the database, etc) that take time. See screenshot below!

Minor improvements and bugfixes

• Added support for GitHub Codespaces (#54)
• Encore now recognizes both Authorization: Token foo as well as Authorization: Bearer foo for authentication
• Added ENCORE_DAEMON_DEV=1 to make it easier to develop the Encore daemon
• Fixed Windows terminal handling (#56)
• Fixed building from source on Windows (#57)
• Fixed json.RawMessage handling in generated TypeScript client (#73)
• Fixed API Explorer sometimes inferring the wrong HTTP method (#74)
• Fixed incorrectly passing in HTTP body for GET requests (#45)
• Fixed API Explorer default payload for float64 (#43)
• Fixed CORS headers for less common HTTP methods
• Fixed int and uint handling in the API Explorer

Contributions and thanks

• @vilhelmmelkstam for his numerous bug reports and bug fixes!
• @frzam for fixing several bugs related to Windows and terminal handling!
• @mvp-joe for lots of great feedback and bug reports over in Encore's Discord community
• And thanks as always to everybody for helping make Encore great.

Encore now has support for defining RESTful APIs in an easy, powerful way!

API Paths

Defining APIs can now include the path=/foo/bar and method=FOO parameters to customize the HTTP path and method the API is exposed at:

type CreateOrderParams struct { /* ... */ }
type Order struct { /* ... */ }    

//encore:api public path=/orders method=POST
func CreateOrder(ctx context.Context, p *CreateOrderParams) (*Order, error) { /* ... */ }

Path parameters

You can also define custom API path parameters such as path=/orders/:id.

When you specify a parameter, Encore passes that parameter directly to your function as a separate argument, like so:

type Order struct { /* ... */ }    

//encore:api public path=/orders/:id method=GET
func GetOrder(ctx context.Context, id int) (*Order, error) { /* ... */ }

Encore automatically performs validation of the parameter, according to the type used in the function signature. In this case id must be an integer. You can also use string, bool, uint8, and so on. You can even use encore.dev/types/uuid.UUID if you want to receive UUIDs.

Conflicting paths

Encore parses all the APIs in your application and ensures they don't conflict. For any given API call there can only ever be zero or one API that matches. If you define paths that conflict, Encore raises a compilation error.

Making API calls between services

Like always, Encore makes it easy to do API calls between services, and these parameterized APIs work just as easily as before: just call the function: service.GetOrder(ctx, 5).

Secrets Management

Encore's Cloud Dashboard now provides much-improved secrets management support. You can view, update, and roll back secrets to previous versions.

Contributions

• Many thanks to @Willyham for initiating the custom API path support and implementing a large part of it!

Encore now supports customizing the HTTP path of API raw endpoints. The next release will include complete support for all types of API endpoints.

//encore:api public raw path=/hello/:name
func Greet(w http.ResponseWriter, req *http.Request) {
    name := strings.TrimPrefix(req.URL.Path, "/hello/")
    fmt.Fprintf(w, "Hello, %s!", name)
}

Encore now includes even better Distributed Tracing support out of the box!

Stack traces

Stack traces are incredibly useful for debugging, but common wisdom is that they're too slow to collect at scale. Encore's deep integration across the stack enabled us to do this in a highly performant way, by only snapshotting program counters at runtime and mapping it to source code information when the trace is viewed. This enables Encore to collect stack traces in less than 300ns!

The end result is that Encore now provides complete stack traces for all events, including API calls, database queries, log messages, and so on.

Automatic HTTP Tracing

Encore now also includes automatic tracing of outgoing HTTP requests. This also works out of the box, and works for all HTTP calls using Go's standard library net/http package.

Hope you enjoy the new release!

Encore now has great built-in support for API errors. Features include:

• Return errors with specific HTTP status codes
• Return structured errors, along with structured additional details
• Support for key-value metadata that is propagated between services

All of this is made possible using the encore.dev/beta/errs package. Read all about it in the Encore docs!

We're happy to announce the first Encore release following the open source announcement two weeks ago: v0.13!

The headline feature of Encore v0.13 is built-in support for Structured API Errors. Beyond that we've made a lot of minor adjustments to improve the onboarding experience, and fixed a lot of bugs that you've reported!

Upgrading Encore

To upgrade, run the appropriate command:

brew install encoredev/tap/encore               # macOS
iwr https://encore.dev/install.ps1 -useb | iex  # Windows
curl -L https://encore.dev/install.sh | bash    # Linux

Office Hours

We're also happy to announce we've started doing Office Hours!

If you want to chat about anything Encore-related, book a session with us here! We love hearing about your experiences with Encore, and what we can do to make it even better.

With that, let's dig in to the release highlight!

Structured API Errors

Encore now supports returning structured error information from your APIs.

The key piece is the new encore.dev/beta/errs package.

The errs.Error type

Structured errors are represented by the errs.Error type:

type Error struct {
    // Code is the error code to return.
    Code ErrCode `json:"code"`
    // Message is a descriptive message of the error.
    Message string `json:"message"`
    // Details are user-defined additional details.
    Details ErrDetails `json:"details"`
    // Meta are arbitrary key-value pairs for use within
    // the Encore application. They are not exposed to external clients.
    Meta Metadata `json:"-"`
}

Returning an *errs.Error from an Encore API endpoint will result in Encore serializing this struct to JSON and returning it in the response. Additionally Encore will set the HTTP status code to match the error code (see the mapping table below).

For example:

return &errs.Error{
    Code: errs.NotFound,
    Message: "sprocket not found",
}

Causes Encore to respond with a HTTP 404 error with body:

{
    "code": "not_found",
    "message": "sprocket not found",
    "details": null
}

Error Wrapping

Encore applications are encouraged to always use the errs package to manipulate errors. It supports wrapping errors to gradually add more error information, and lets you easily define both structured error details to return to external clients, as well as internal, key-value metadata for debugging and error handling.

func Wrap(err error, msg string, metaPairs ...interface{}) error

Use errs.Wrap to conveniently wrap an error, adding additional context and converting it to an *errs.Error. If err is nil it returns nil. If err is already an *errs.Error it copies the Code, Details, and Meta fields over.

The variadic metaPairs parameter must be key-value pairs, where the key is always a string and the value can be any built-in type. Existing key-value pairs from the err are merged into the new *Error.

func WrapCode(err error, code ErrCode, msg string, metaPairs ...interface{}) error

errs.WrapCode is like errs.Wrap but also sets the error code.

func Convert(err error) error

errs.Convert converts an error to an *errs.Error. If the error is already an *errs.Error it returns it unmodified. If err is nil it returns nil.

Error Codes

The errs package defines error codes for common error scenarios. They are identical to the codes defined by gRPC for interoperability.

The table below summarizes the error codes. You can find additional documentation about when to use them in the package documentation.

Error Building

In cases where you have complex business logic, or multiple error returns, it's convenient to gradually add metadata to your error.

For this purpose Encore provides errs.Builder. The builder lets you gradually set aspects of the error, using a chaining API design. Use errs.B() to get a new builder that you can start chaining with directly.

When you want to return the constructed error call the .Err() method.

For example:

func getBoard(ctx context.Context, boardID int64) (*Board, error) {
    // Construct a new error builder with errs.B()
    eb := errs.B().Meta("board_id", params.ID)

    b := &Board{ID: params.ID}
    err := sqldb.QueryRow(ctx, `
        SELECT name, created
        FROM board
        WHERE id = $1
    `, params.ID).Scan(&b.Name, &b.Created)
    if errors.Is(err, sqldb.ErrNoRows) {
        // Return a "board not found" error with code == NotFound
        return nil, eb.Code(errs.NotFound).Msg("board not found").Err()
    } else if err != nil {
        // Return a general error
        return nil, eb.Cause(err).Msg("could not get board").Err()
    }
    // ...
}

Inspecting API Errors

When you call another API within Encore, the returned errors are always wrapped in *errs.Error.

You can inspect the error information either by casting to *errs.Error, or using the below helper methods.

func Code(err error) ErrCode

errs.Code returns the error code. If the error was not an *errs.Error it returns errs.Unknown.

func Meta(err error) Metadata
type Metadata map[string]interface{}

errs.Meta returns any structured metadata present in the error. If the error was not an *errs.Error it returns nil. Unlike when you return error information to external clients, all the metadata is sent to the calling service, making debugging even easier.

func Details(err error) ErrDetails

errs.Details returns the structured error details. If the error was not an *errs.Error or the error lacked details, it returns nil.

Coming up next

We've lots of great things planned for Encore.

The next big thing we're working on is being able to integrate Encore applications with existing infrastructure, to more easily adopt it for existing applications.

This means being able to connect it up to existing databases, being able to deploy to existing Kubernetes clusters, and even deploying Encore applications to regular VMs and other deployment options. We'll start on the database side and gradually expand our support in this space.

We're also looking at expanding our database support, adding a GraphQL API, better support for ORMs for people who prefer that, and more.

We're still working on gathering all your feedback and assembling it into a roadmap of some kind, but please continue letting us know what you'd like to see!

The best way is to open an issue at github.com/encoredev/encore, or reach me on Twitter.

Encore now adds structured log messages to the automatic tracing, using encore.dev/rlog. Log messages written during traced requests are automatically added to the trace.

The structure of additional fields is preserved, allowing us to index and filter by structured log context later!

This release fixes a few minor issues discovered following the open-source release:

• Fix encore db shell for local development
• Add log message when a request to an auth endpoint lacks an Authorization header
• Improved help for encore gen client
• Other miscellaneous fixes