Integrating with Golang Apps

In some cases, it can be useful to embed a RoadRunner server inside another Go program. This is often the case in microservice architectures where you may have a mandated Go framework for all the apps. In such cases, it might not be possible to run a stock RoadRunner instance, and the only choice is to run RoadRunner inside the main app framework/ program.

Here's an example of how to embed RoadRunner into a Go program with an HTTP handler:

Use Go 1.27.1. Import the RoadRunner library. Use the same commit SHA as your source build when you need a fixed revision:

go get github.com/roadrunner-server/roadrunner/v3/lib@latest

The library imports v6 plugins and uses the v6 plugin contracts. NewRR returns (*RR, error).

Create an RR instance

import (
    "github.com/roadrunner-server/roadrunner/v3/lib"
)

func main() {
    overrides := []string{} // List of configuration overrides
    plugins := lib.DefaultPluginsList() // List of RR plugins to enable
    rr, err := lib.NewRR(".rr.yaml", overrides, plugins)
}

Here we use the default list of plugins. This is the same list of plugins you would get if you were to run rr serve with a stock RoadRunner binary.

You can select plugins and add your own plugin. Replace example.com/my-plugin with your module path. The omitted entries must include the dependencies required by the selected plugins:

Starting & stopping embedded RoadRunner

Once everything is ready, we can start the RoadRunner instance:

rr.Serve() will block until it returns an error or nil if it was stopped gracefully.

To gracefully stop the server, simply call rr.Stop().