I’m excited to let you all know we’ve just published the v2 API of ngrok-go, our idiomatic open-source Go package for embedding ngrok directly into your Go applications. This v2 update modernizes the API, simplifies integration, and exposes new ngrok platform features for a leaner, more idiomatic interface that’s easier to learn, use, and maintain.
With just a few lines of code, ngrok-go adds a secure, environment-agnostic API gateway in front of your Go application—no matter where it runs. When you use ngrok-go, you will receive traffic the same way no matter where you run your app: any cloud, CI environment, on your laptop, … anywhere.
Over the last two years, ngrok-go has been adopted by thousands of developers and integrated into 80+ open source packages. Meanwhile, ngrok’s own platform has evolved—prompting a major upgrade to keep the SDK in step. Let’s take a closer look at what’s new in v2.
Let’s try ngrok-go v2! First, install the SDK with:
go get golang.ngrok.com/ngrok/v2Then export your auth token by entering the following in your terminal:
export NGROK_AUTHTOKEN=<your_auth_token>And go run the following code:
package main
import (
"context"
"fmt"
"log"
"net/http"
"golang.ngrok.com/ngrok/v2"
)
func main() {
l, err := ngrok.Listen(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println("endpoint url: ", l.URL())
http.Serve(l, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "Hello from your ngrok-delivered Go app!")
}))
}Traffic Policy is ngrok’s configuration language that enables you to filter, match, manage, and orchestrate traffic with a simple CEL-based rules engine. Much of the v1 package API has been replaced with Traffic Policy. Let’s see how easy that is to use to add authentication to an endpoint:
package main
import (
"context"
"fmt"
"log"
"net/http"
"golang.ngrok.com/ngrok/v2"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
const trafficPolicy = `
on_http_request:
- name: OAuth
actions:
- type: oauth
config:
auth_id: oauth
provider: google
- name: bad email
expressions:
- actions.ngrok.oauth.identity.email != 'alan@example.com'
actions:
- type: custom-response
config:
body: "Access denied: ${actions.ngrok.oauth.identity.name}!"
status_code: 403
`
func run(ctx context.Context) error {
// Create an HTTP listener with the traffic policy
ln, err := ngrok.Listen(ctx,
ngrok.WithTrafficPolicy(trafficPolicy),
ngrok.WithDescription("traffic policy example"),
)
if err != nil {
return err
}
// Serve HTTP traffic on the ngrok endpoint
log.Println("Endpoint online", ln.URL())
return http.Serve(ln, http.HandlerFunc(handler))
}
func handler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, %s\n", r.Header.Get("authenticated-user"))
}Although it may seem unconventional at first to define traffic policy as YAML instead of typed Go code, we’ve found this approach greatly enhances the user experience. YAML-based traffic policies are easy to test, share, and reuse across Cloud Endpoints, Agent Endpoints, the Kubernetes Operator, and SDKs. You can copy and modify examples from documentation or the community with ease. Additionally, using Traffic Policy enables access to new traffic features without needing to upgrade your SDK.
First, install the SDK: go get golang.ngrok.com/ngrok/v2
Then check out our other resources:
We distribute agent SDK libraries in Go, Rust, Python and Javascript. Go is the first agent SDK to get a 2.0 facelift, but you can expect us to roll out improved APIs for all languages over the remainder of the year.
If you have questions or feedback about ngrok-go v2 or any of our SDKs, why not pop into our Discord server? We'd be happy to help you over there and hear you to make things better.