Mock it till you drop it: API and Service mocking support is here

With v1.30.0 we're now introducing support for mocking APIs and services! This makes it much simpler to test your application in isolation.

Let's look at an example:

You have an endpoint that calls an external API in our products service:

//encore:api private
func GetPrice(ctx context.Context, p *PriceParams) (*PriceResponse, error) {
    // Call external API to get the price
}

When testing this function, you don't want to call the real external API since that would be slow and cause your tests to fail if the API is down. Instead, you want to mock out the API call and return a fake response.

You can now do this in Encore by adding a mock implementation of the endpoint using the et.MockEndpoint function inside your test:

package shoppingcart

import (
	"context"
	"testing"
	
	"encore.dev/et" // Encore's test support package
	
	"your_app/products"
)


func Test_Something(t *testing.T) {
	t.Parallel() // Run this test in parallel with other tests without the mock implementation interfering
	
	// Create a mock implementation of pricing API which will only impact this test and any sub-tests
	et.MockEndpoint(products.GetPrice, func(ctx context.Context, p *products.PriceParams) (*products.PriceResponse, error) {
		return &products.PriceResponse{Price: 100}, nil
	})
	
	// ... the rest of your test code here ...
} 

In addition to mocking individual APIs, you can also mock entire services. This can be useful if you want to inject a different set of dependencies into your service for testing, or a service that your code depends on.

When mocking services, Encore will automatically generate an Interface interface for every service, which contains all the APIs defined in the service. This makes it possible to automatically generate mock objects for your services using either Mockery or GoMock.

📚 Check out the docs for all the details.

👉 Remember to update using: encore version update

Improved docs search

We've updated the docs search functionality to make it easier to find what you're looking for. Search now has improved relevancy, snippets are much improved, and results can now link directly to sub-sections of individual pages.

Roadmap

We're currently pushing to get TypeScript support out the door and hope to release the first general availability in the next few weeks.
We've also been working on some smaller features based on your comments on Slack which will drop in the next few days: cloud cost insights and the ability to pause and trigger cron jobs from the Cloud Dashboard.

Check out the roadmap and leave your comments!

Thanks to all contributors

🙏 We continue to be overwhelmed by your support, feedback, and suggestions!
Together we're building the future of backend development and we couldn't be more excited.

❤️ As always, we're excited to hear what you think!
Please share your feedback on Slack.

Full Changelog: encoredev/encore@v1.29.7...v1.30.0

Configure the World!

Or maybe just your application to start with.

In this release, we're introducing a new config package that combines the power of CUE lang with the smooth Encore developer experience. It gives you both the type safety of Go, and the powerful flexibility of CUE. This lets you focus on writing your business logic, safe in the knowledge that Encore's compiler will prevent invalid configurations from ever reaching your production environment.

To use it, you simply call config.Load[*MyConfigType]() and assign the returned instance of your config type to a package-level variable (Remember to first update with encore version update.)

As with many of Encore's features, config comes with isolated test support. This allows you to override configuration values on inside tests, without impacting any other concurrently running tests.

For more information about Encore native config support, check out the docs.

Bugfixes and other improvements

We're always thankful when we get feedback and bug reports from anyone using Encore!
Here are some improvements we've made lately, thanks to your input:

• Added documentation to the encore.dev Go package to explain why those functions all panic, as well as including links to the underlying implementation
• Fixed an issue with walking recursive types
• Fixed an issue with the rendering of pointer types in the development dashboard
• Improved the documentation by improving clarity on some pages, rewriting others and fixing various typos.

Thanks to our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. A huge thank you to @SarojWasti & @ArjunSharda for your contributions to this release!

What's next

Over the next couple of weeks, we're going to release a next-generation cloud provisioning system for Encore. Check out this blog post to get a sneak preview. – Remember to vote on your favorite feature on the roadmap!

As always, if you have questions or feedback, tell us on Slack or our Community Forums.

We're excited to hear your feedback! ❤️

Catch you in the cloud,
Dom & the Encore team

Introducing next-generation error reports

If there's an error, at least it's a nice one now

Compiler errors are a source of frustration for most developers, as they often force us to decipher confusing or misleading error messages. To make this a better experience we've taken inspiration from Elm and Rust, and we've modified how Encore reports into human-readable errors.

Instead of simply reporting a filename, line number, and column number with a single line of text describing the error, Encore now shows a summary of the error, the line(s) of code which caused the error, and also show other lines of code to provide additional context.

All errors returned by Encore will now render in this format. Over the coming months, we plan to improve the readability of all errors by providing additional context or help text within the error itself.

GoLand Plugin

We are happy to announce that Encore now has an official plugin for GoLand and IntelliJ. The plugin allows you to run unit tests on Encore applications from the comfort of your IDE, as well as allowing you to run those same tests in debug mode with breakpoint support!

As with Encore itself, the plugin is open source. Bug reports and contributions are welcome at encoredev/intellij-plugin.

Download the plugin today: https://plugins.jetbrains.com/plugin/20010-encore/

Bugfixes and other improvements

We're always thankful when we get feedback and bug reports from anyone using Encore. Here are some improvements we've made lately, thanks to your input:

• We've made multiple improvements to the local dashboard from fixing the font loading to adding scrolling to the logs shown in the trace view.
• When you use the encore logs command to stream logs, we show a "waiting for logs" message to indicate that the stream is connected successfully.
• We've fixed an issue with authorization tokens to the Encore platform becoming corrupted and not refreshing correctly.
• Fixed a bug where if a DI-based API was used in a cronjob, Encore was unable to parse the application if the encore.gen.go file was missing. (Thanks @Willyham for the bug report)
• Various improvements to the documentation.

Thanks to our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. A huge thank you to @kVarunkk, @eddy-geek, @AM1TB, @Minivera, @michizhou for your contributions to this release!

What's next

Over the next couple of weeks, we're super excited to announce we'll be releasing Encore native support for per-service configuration, powered by the CUE language. Remember to vote on your favourite feature on the roadmap!

As always, if you have questions or feedback, tell us on Slack or our Community Forums.

We're excited to hear your feedback! ❤️

Catch you in the cloud,
Dom & the Encore team

Full Changelog: encoredev/encore@v1.7.0...v1.8.0

Introducing Caches: Use Redis as a native code concept in Encore

In-memory caches are vital when you're building real-time applications like games, ad systems, or financial applications. They're also practical when you want a convenient way to store key values without needing a database. That's why we're excited to let you know that Encore now has native support for in-memory caches, using Redis!

Here's what you need to know

• The Encore framework now has a native API for working with caches, and as usual, it works the same across Encore cloud, GCP, and AWS. (Azure coming soon!)
• Before trying it out, remember to first update using: encore version update

Check out the docs to see how the new cache API works.

Upgrades to Encore Flow

We've also been busy making improvements to Encore Flow:

• Cron Jobs are now included in the Encore Flow architecture diagrams, making it dead simple to see which services have Cron Jobs attached.
• You can now easily download an image of your system architecture using the little camera icon in the upper right corner of the Encore Flow view.

Local dev dash refresh

It's been a long time coming, but it's finally done: The local dev dash is now using the same styling as the web platform! We've also made a bunch of usability improvements to make it more intuitive and easier to use. We'd love to hear what you think on Slack!

Bugfixes and other improvements

We're always thankful when we get feedback and bug reports from anyone using Encore. Here are some improvements we've made lately, thanks to your input:

• We've given the Encore website a big performance boost, so it loads faster and feels snappier!
• We've improved the responsiveness and layout of the docs section so it's easier to use side-by-side with your IDE.
• We fixed a bug where Flow wouldn't render properly on Firefox.

Thanks to our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement.
Thanks to @bogdaaamn, @Minivera, @Willyham, @davidmytton, @melkstam, MaxD for your ideas, bug reports and feedback!

Introducing our new community forums

For a long time, we've had an active Slack group. It's been a great way for everyone to engage in meaningful conversations, and for us quickly provide help when there are questions. Lately, we've noticed that the drawback with Slack is that it makes it hard for new joiners to discover answers to common questions and refer to past conversations.

That's why we've launched a community forum!

We'll use this for asynchronous conversations and to build up a knowledge base of community questions and answers.

• If you haven't already, sign up and introduce yourself!

We're not going to stop using Slack, rather we're going to focus it on synchronous and time-sensitive conversations.

What's next

In the coming weeks we'll be adding even more flexibility to the Encore framework, with improved support for configuration. We're also working on a big upgrade to infrastructure provisioning, making it more flexible and easier for you to add specific requirements like deploying to existing Kubernetes clusters. - Remember to vote on your favorite feature on the roadmap!

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

We're excited to hear your feedback! ❤️

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

Middleware, Validation, Dependency Injection, oh my!

We're excited to announce Encore now supports three of the most highly requested features: Middleware, Validation support, and Dependency Injection! Each one is large enough to warrant its own release but here's a three-for-one!

This means you can now:

• Define service-specific or global middleware to implement cross-cutting concerns spanning several endpoints
• Automatically validate incoming requests before invoking handlers
• Simplify testing of Encore APIs and services
• Hook into the service initialization and graceful shutdown process for custom logic

🥐 Run encore version update to grab the latest version, or read on for more information.

Encore Middleware

Middleware has been one of the most highly requested Encore features, and it's finally here! Unlike typical Go HTTP middleware, Encore's middleware operates on fully unmarshalled types which enables some incredible workflows. Here's how you define a middleware:

import (
    "encore.dev/middleware"
    "encore.dev/rlog"
)

//encore:middleware target=all
func MyMiddleware(req middleware.Request, next middleware.Next) middleware.Response {
    resp := next(req)
    rlog.Info("returning response", "payload", resp.Payload)
    return resp
}

See the middleware docs for more information!

Validation support

Encore now supports request validation out of the box! To use it, simplify define a Validate() error method on your request types. For example:

//encore:api public
func MyEndpoint(ctx context.Context, p *Params) error {
    // ...
}

type Params struct {
    Worry bool
}

func (p *Params) Validate() error {
    if p.Worry {
        return errors.New("don't worry, be happy")
    }
    return nil
}

See the validation docs for more information!

Dependency Injection

You can now define Encore APIs as methods on a Service Struct, which allows you to use dependency injection for easier testing of your Encore API endpoints. It introduces the new //encore:service directive that you can use to define a struct type as a Service Struct. It looks like this:

//encore:service
type Service struct { /* dependencies go here */ }

//encore:api public
func (s *Service) MyAPI(ctx context.Context) error { /* ... */ }

The new Service Struct approach also comes with several other features, like service initialization and graceful shutdown hooks!
Read the docs on Service Structs and
Dependency Injection for more information.

Bug fixes and other improvements

• Fixed a case where the runtime was not fully initialized for test-only packages using sqldb.Named (#335)
• Fixed trace viewer tooltip being difficult to hover into (#332)
• Fixed encore.dev/docs keyboard shortcuts

Thanks to our contributors

We rely on the community to improve Encore, and we're overwhelmed by your support and encouragement. Thanks to @Willyham, @melkstam, @bjaanes, @Minivera, @davidmytton, @maxd and others for your feedback and contributions!

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Slack 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 support for configuration, Azure Pub/Sub, caching, 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 Slack or just reply to this email.

We're excited to hear your feedback! ❤️

Catch you in the cloud,

The Encore Team

Introducing Encore PubSub

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 Slack 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 Slack.
We’re excited to hear your feedback! ❤️

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

Introducing the Encore App Metadata API

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.

Join the most pioneering developer community

Developers building with Encore are forward-thinkers working on exciting and innovative products. Join the conversation on Slack 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 Slack or just reply to this email.
We're excited to hear your feedback! ❤️

Catch you in the cloud,
The Encore team