You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+3-7Lines changed: 3 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,14 +16,10 @@ For any larger changes or features, please [open a new issue](https://github.com
16
16
17
17
The library can be compiled with `go build`.
18
18
19
-
To run tests, `go test`.
19
+
To run tests, use `go test ./...`.
20
20
21
21
Tests are split into a number of categories that can be enabled as desired via environment variables. By default, only offline tests run which validate tunnel protocol RPC messages generated from the `config` APIs. The other tests are gated behind the following environment variables:
22
22
23
-
*`NGROK_TEST_ONLINE`: All online tests require this variable to be set
24
-
*`NGROK_TEST_AUTHED`: Enables tests that require an ngrok account and that the authtoken is set in `NGROK_AUTHTOKEN`.
25
-
*`NGROK_TEST_PAID`: Enables online, authenticated tests that require access to paid features. If your subscription doesn't support a feature being tested, you should see error messages to that effect.
26
-
*`NGROK_TEST_LONG`: Enables online tests that may take longer than most. May also require the `AUTHED` and/or `PAID` groups enabled.
27
-
*`NGROK_TEST_FLAKEY`: Enable online tests that may be unreliable. Their success or failure may depend on network conditions, timing, solar flares, ghosts in the machine, etc.
23
+
*`NGROK_TEST_ONLINE`: All online tests require this variable to be set and an authtoken in `NGROK_AUTHTOKEN`. Tests that require paid features will fail with appropriate error messages if your subscription doesn't support them.
28
24
29
-
This list may be incomplete and drift slightly as we add more tests and granularity. See the tests in `online_test.go` for the most accurate list.
25
+
This list may be incomplete and drift slightly as we add more tests and granularity. See the tests in `internal/legacy/online_test.go`and `integration_test.go`for the most accurate implementations.
[ngrok](https://ngrok.com) is a simplified API-first ingress-as-a-service that adds connectivity, security, and observability to your apps.
8
+
[ngrok](https://ngrok.com) is an API gateway cloud service that forwards to
9
+
applications running anywhere.
9
10
10
-
ngrok-go is an open source and idiomatic library for embedding ngrok networking directly into Go applications. If you’ve used ngrok before, you can think of ngrok-go as the ngrok agent packaged as a Go library.
11
+
ngrok-go is an open source and idiomatic Go package for embedding ngrok
12
+
networking directly into your Go applications. If you've used ngrok before, you
13
+
can think of ngrok-go as the ngrok agent packaged as a Go library.
11
14
12
-
ngrok-go lets developers serve Go apps on the internet in a single line of code without setting up low-level network primitives like IPs, certificates, load balancers and even ports! Applications using ngrok-go listen on ngrok’s global ingress network but they receive the same interface any Go app would expect (net.Listener) as if it listened on a local port by calling net.Listen(). This makes it effortless to integrate ngrok-go into any application that uses Go's net or net/http packages.
13
-
14
-
See [`examples/http/main.go`](/examples/http/main.go) for example usage, or the tests in [`online_test.go`](/online_test.go).
15
+
ngrok-go enables you to serve Go apps on the internet in a single line of code
16
+
without setting up low-level network primitives like IPs, certificates, load
17
+
balancers and even ports! Applications using ngrok-go listen on ngrok's global
18
+
cloud service but they receive connections using the same interface
19
+
(net.Listener) that any Go app would expect if it listened on a local port.
15
20
16
21
For working with the [ngrok API](https://ngrok.com/docs/api/), check out the [ngrok Go API Client Library](https://github.com/ngrok/ngrok-api-go).
17
22
18
23
## Installation
19
24
20
-
The best way to install the ngrok agent SDK is through`go get`.
25
+
Install ngrok-go with`go get`.
21
26
22
27
```sh
23
-
go get golang.ngrok.com/ngrok
28
+
go get golang.ngrok.com/ngrok/v2
24
29
```
25
30
26
31
## Documentation
27
32
28
-
A full API reference is included in the [ngrok go sdk documentation on pkg.go.dev](https://pkg.go.dev/golang.ngrok.com/ngrok). Check out the [ngrok Documentation](https://ngrok.com/docs) for more information about what you can do with ngrok.
29
-
30
-
For additional information, be sure to also check out the [ngrok-go launch announcement](https://ngrok.com/blog-post/ngrok-go)!
33
+
-[ngrok-go API Reference](https://pkg.go.dev/golang.ngrok.com/ngrok/v2) on pkg.go.dev.
34
+
-[ngrok Documentation](https://ngrok.com/docs) for what you can do with ngrok.
35
+
-[Examples](./examples) are another great way to get started.
36
+
-[ngrok-go launch announcement](https://ngrok.com/blog-post/ngrok-go) for more context on why we built it. The examples in the blog post may be out of date for the new API.
31
37
32
38
## Quickstart
33
39
34
-
For more examples of using ngrok-go, check out the [/examples](/examples) folder.
35
-
36
-
The following example uses ngrok to start an http endpoint with a random url that will route traffic to the handler. The ngrok URL provided when running this example is accessible by anyone with an internet connection.
40
+
The following example starts a Go web server that receives traffic from an
41
+
endpoint on ngrok's cloud service with a randomly-assigned URL. The ngrok URL
42
+
provided when running this example is accessible by anyone with an internet
43
+
connection.
37
44
38
-
The ngrok authtoken is pulled from the `NGROK_AUTHTOKEN` environment variable. You can find your authtoken by logging into the [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).
45
+
You need an ngrok authtoken to run the following example, get yours from the
You can run this example with the following command:
48
+
Run this example with the following command:
41
49
42
50
```sh
43
51
NGROK_AUTHTOKEN=xxxx_xxxx go run examples/http/main.go
@@ -52,8 +60,7 @@ import (
52
60
"log"
53
61
"net/http"
54
62
55
-
"golang.ngrok.com/ngrok"
56
-
"golang.ngrok.com/ngrok/config"
63
+
"golang.ngrok.com/ngrok/v2"
57
64
)
58
65
59
66
funcmain() {
@@ -63,16 +70,16 @@ func main() {
63
70
}
64
71
65
72
funcrun(ctxcontext.Context) error {
66
-
ln, err:= ngrok.Listen(ctx,
67
-
config.HTTPEndpoint(),
68
-
ngrok.WithAuthtokenFromEnv(),
69
-
)
73
+
// ngrok.Listen uses ngrok.DefaultAgent which uses the NGROK_AUTHTOKEN
74
+
// environment variable for auth
75
+
ln, err:= ngrok.Listen(ctx)
70
76
if err != nil {
71
77
return err
72
78
}
73
79
74
-
log.Println("Ingress established at:", ln.URL())
80
+
log.Println("Endpoint online", ln.URL())
75
81
82
+
// Serve HTTP traffic on the ngrok endpoint
76
83
return http.Serve(ln, http.HandlerFunc(handler))
77
84
}
78
85
@@ -81,6 +88,15 @@ func handler(w http.ResponseWriter, r *http.Request) {
81
88
}
82
89
```
83
90
91
+
## Examples
92
+
93
+
There are many great examples you can copy to get started:
94
+
95
+
-[Creating a TCP endpoint](./examples/tcp/) and handling TCP connections directly.
96
+
-[Forwarding to another URL](./examples/forward/) instead of handling connections yourself.
97
+
-[Adding Traffic Policy](./examples/traffic-policy/) in front of your app for authentication, rate limiting, etc.
98
+
-[Integrating with slog](./examples/slog/) for structured logging
99
+
84
100
## Support
85
101
86
102
The best place to get support using ngrok-go is through the [ngrok Slack Community](https://ngrok.com/slack). If you find bugs or would like to contribute code, please follow the instructions in the [contributing guide](/CONTRIBUTING.md).
@@ -102,4 +118,4 @@ Changes to `ngrok-go` are tracked under [CHANGELOG.md](https://github.com/ngrok/
102
118
103
119
ngrok-go is licensed under the terms of the MIT license.
0 commit comments