Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/brettbuddin/pass
A library for creating configurable reverse-proxies.
https://github.com/brettbuddin/pass
go golang http library reverse-proxy
Last synced: 5 days ago
JSON representation
A library for creating configurable reverse-proxies.
- Host: GitHub
- URL: https://github.com/brettbuddin/pass
- Owner: brettbuddin
- License: mit
- Created: 2021-01-10T15:19:44.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-02-21T19:56:35.000Z (almost 4 years ago)
- Last Synced: 2024-06-20T10:19:28.456Z (7 months ago)
- Topics: go, golang, http, library, reverse-proxy
- Language: Go
- Homepage:
- Size: 60.5 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pass
[](https://pkg.go.dev/github.com/brettbuddin/pass)
Pass is a library for building reverse-proxies. It wraps
[`httputil.ReverseProxy`](https://golang.org/pkg/net/http/httputil/#ReverseProxy),
and specifies routing via configuration files.
## Configuration
Routing in Pass is configured via HCL. This enables proxy routing to be
configured outside of your binary's code—such as Kubernetes `ConfigMap`
definitions.
```hcl
// Base prefix for all upstream routes. (optional)
prefix_path = "/api/v2"
// Annotations for this Manifest that can be used by other libraries once
// this Manifest is parsed. Similar to Kubernetes Annotations, they enable other
// libraries and tooling to apply meaning to the Manifest. These values are
// arbitrary to the pass library.
annotations = {
"company/version": 2
}
// Define an upstream service called "widgets". The identifier here is just a
// human readable string to refer to this service. For instance, you could use
// this identifier when tagging metrics.
upstream "widgets" {
// Annotations for this upstream destination.
annotations = {
"company/middleware": "jwt,tracing"
}
// Location in the form of "scheme://hostname" to send the traffic.
destination = "http://widgets.local"
// Team identifier to help keep track of who's the point of contact for a
// particular upstream service. (optional)
owner = "Team A "
// Inform the reverse-proxy to flush the response body every second. If this
// is omitted, no flushing will be peformed. A negative value will flush
// immediately after each write to the client. (optional)
flush_interval_ms = 1000
// Add an additional prefix segment (added to the root level `prefix_path`)
// that should be stripped from outgoing requests. (optional)
prefix_path = "/private"
// GET `/api/v2/private/widgets` -> GET `http://widgets.local/widgets`
// POST `/api/v2/private/widgets` -> POST `http://widgets.local/widgets`
route {
methods = ["GET", "POST"]
path = "/widgets"
}
// GET `/api/v2/private/widgets/123` -> GET `http://widgets.local/widgets/123`
// PUT `/api/v2/private/widgets/123` -> PUT `http://widgets.local/widgets/123`
// DELETE `/api/v2/private/widgets/123` -> DELETE `http://widgets.local/widgets/123`
route {
methods = ["GET", "PUT", "DELETE"]
path = "/widgets/{[0-9]+}"
}
}
upstream "gears" {
destination = "http://gears.local"
owner = "Team B "
prefix_path = "/gears"
// ANY METHOD /api/v2/gears/anything -> http://gears.local/api/v2/gears/anything
route {
methods = ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"]
path = "/*"
}
// ANY METHOD /api/v2/gears -> http://gears.local/api/v2/gears
route {
methods = ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"]
path = "/"
}
}
```
Parsing the file and mounting it in your application:
```go
m, err := pass.LoadManifest("./manifest.hcl", nil)
if err != nil {
return err
}
// Register the manifest's routes with a router.
proxy, err := pass.New(m)
if err != nil {
return err
}
```
You can pass an optional `hcl.EvalContext` to specify variables and functions as
part of the HCL parsing.
```go
ectx := &hcl.EvalContext{
Variables: map[string]cty.Value{
"namespace": cty.StringVal("example"),
},
}
// The variable "namespace" will be available in this configuration file.
m, err := pass.LoadManifest("./manifest.hcl", ectx)
if err != nil {
return err
}
```
## Examples
Check out the [example/](example) directory for usage examples in code.