7 |
8 | ## Features
9 |
10 | Bramble supports:
11 |
12 | - Shared types across services
13 | - Namespaces
14 | - Field-level permissions
15 | - Plugins:
16 | - JWT, Open tracing, CORS, ...
17 | - Or add your own
18 | - Hot reloading of configuration
19 |
20 | It is also stateless and scales very easily.
21 |
22 | ## Future work/not currently supported
23 |
24 | There is currently no support for subscriptions.
25 |
26 | ## Contributing
27 |
28 | Contributions are always welcome!
29 |
30 | If you wish to contribute please open a pull request. Please make sure to:
31 |
32 | - include a brief description or link to the relevant issue
33 | - (if applicable) add tests for the behaviour you're adding/modifying
34 | - commit messages are descriptive
35 |
36 | Before making a significant change we recommend opening an issue to discuss
37 | the issue you're facing and the proposed solution.
38 |
39 | ### Building and testing
40 |
41 | Prerequisite: Go 1.23
42 |
43 | To build the `bramble` command:
44 |
45 | ```bash
46 | go build -o bramble ./cmd
47 | ./bramble -config config.json
48 | ```
49 |
50 | To run the tests:
51 |
52 | ```bash
53 | go test ./...
54 | ```
55 |
56 | ## Comparison with other projects
57 |
58 | Bramble provides a common-sense approach to GraphQL federation implemented in Golang. It assumes that subgraph fields are mutually exclusive, and that all boundary types join on a universal key. Compared with other projects:
59 |
60 | - [Apollo Federation](https://www.apollographql.com/) and [Golang port](https://github.com/jensneuse/graphql-go-tools): while quite popular, we felt the Apollo spec was more complex than necessary with its nuanced GraphQL SDL and specialized `_entities` query, and thus not the right fit for us.
61 |
62 | - [GraphQL Tools Stitching](https://www.graphql-tools.com/docs/schema-stitching/stitch-combining-schemas): while Stitching is similar in design to Bramble with self-contained subgraphs joined by basic queries, it offers more features than necessary at the cost of some performance overhead. It is also written in JavaScript where as we favour Golang.
63 |
64 | - [Nautilus](https://github.com/nautilus/gateway): provided a lot of inspiration for Bramble, and has been improved upon with bug fixes and additional features (fine-grained permissions, namespaces, better plugins, configuration hot-reloading). Bramble is a recommended successor.
65 |
66 | Bramble is a central piece of software for [Movio](https://movio.co) products and thus is actively maintained and developed.
67 |
--------------------------------------------------------------------------------
/go.mod:
--------------------------------------------------------------------------------
1 | module github.com/movio/bramble
2 |
3 | go 1.23.3
4 |
5 | require (
6 | github.com/99designs/gqlgen v0.17.73
7 | github.com/felixge/httpsnoop v1.0.4
8 | github.com/fsnotify/fsnotify v1.5.1
9 | github.com/golang-jwt/jwt/v4 v4.5.2
10 | github.com/golang/protobuf v1.5.4 // indirect
11 | github.com/gorilla/websocket v1.5.0 // indirect
12 | github.com/graph-gophers/graphql-go v1.5.0
13 | github.com/prometheus/client_golang v1.11.1
14 | github.com/prometheus/common v0.31.1 // indirect
15 | github.com/prometheus/procfs v0.7.3 // indirect
16 | github.com/rs/cors v1.7.0
17 | github.com/stretchr/testify v1.10.0
18 | github.com/vektah/gqlparser/v2 v2.5.27
19 | golang.org/x/crypto v0.38.0 // indirect
20 | golang.org/x/sync v0.14.0
21 | golang.org/x/sys v0.33.0 // indirect
22 | google.golang.org/protobuf v1.36.6 // indirect
23 | )
24 |
25 | require (
26 | github.com/agnivade/levenshtein v1.2.1 // indirect
27 | github.com/beorn7/perks v1.0.1 // indirect
28 | github.com/cespare/xxhash/v2 v2.2.0 // indirect
29 | github.com/davecgh/go-spew v1.1.1 // indirect
30 | github.com/gofrs/uuid v4.2.0+incompatible
31 | github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
32 | github.com/pmezard/go-difflib v1.0.0 // indirect
33 | github.com/prometheus/client_model v0.2.0 // indirect
34 | gopkg.in/yaml.v3 v3.0.1 // indirect
35 | )
36 |
37 | require (
38 | github.com/google/uuid v1.6.0 // indirect
39 | github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
40 | github.com/sosodev/duration v1.3.1 // indirect
41 | go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.52.0
42 | go.opentelemetry.io/otel v1.27.0
43 | go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.27.0
44 | go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.27.0
45 | go.opentelemetry.io/otel/metric v1.27.0 // indirect
46 | go.opentelemetry.io/otel/sdk v1.27.0
47 | go.opentelemetry.io/otel/sdk/metric v1.27.0
48 | go.opentelemetry.io/otel/trace v1.27.0
49 | )
50 |
51 | require github.com/go-jose/go-jose/v4 v4.0.5
52 |
53 | require (
54 | github.com/cenkalti/backoff/v4 v4.3.0 // indirect
55 | github.com/go-logr/logr v1.4.1 // indirect
56 | github.com/go-logr/stdr v1.2.2 // indirect
57 | github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
58 | github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 // indirect
59 | go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.27.0 // indirect
60 | go.opentelemetry.io/proto/otlp v1.2.0 // indirect
61 | golang.org/x/net v0.40.0 // indirect
62 | golang.org/x/text v0.25.0 // indirect
63 | google.golang.org/genproto/googleapis/api v0.0.0-20240520151616-dc85e6b867a5 // indirect
64 | google.golang.org/genproto/googleapis/rpc v0.0.0-20240515191416-fc5f0ca64291 // indirect
65 | google.golang.org/grpc v1.64.1 // indirect
66 | )
67 |
--------------------------------------------------------------------------------
/docs/write-plugin.md:
--------------------------------------------------------------------------------
1 | # Writing a plugin
2 |
3 | ## Plugin interface
4 |
5 | Plugins must implement the [`Plugin`](https://pkg.go.dev/github.com/movio/bramble/bramble#Plugin) interface. Optionaly they can derive from
6 | the [`BasePlugin`](https://pkg.go.dev/github.com/movio/bramble/bramble#BasePlugin) implementation as to avoid redefining all methods.
7 |
8 | ```go
9 | type MyPlugin struct {
10 | bramble.Plugin
11 | }
12 |
13 | func (p *MyPlugin) ID() string {
14 | return "my-plugin"
15 | }
16 | ```
17 |
18 | ## Plugin registration
19 |
20 | Plugins must register themselves using `RegisterPlugin`.
21 | Once registered they can be enabled and configured through Bramble's configuration.
22 |
23 | ```go
24 | func init() {
25 | bramble.RegisterPlugin(&MyPlugin{})
26 | }
27 | ```
28 |
29 | ?> The `init` function can be defined multiple times in the same package.
30 |
31 | ## Compiling Bramble with custom Plugins
32 |
33 | To build Bramble with custom plugins simply create your own `main.go` with an anonymous import of your plugins' package.
34 |
35 | ```go
36 | package main
37 |
38 | import (
39 | "github.com/movio/bramble"
40 | _ "github.com/movio/bramble/plugins"
41 | _ "github.com/your/custom/package"
42 | )
43 |
44 | func main() {
45 | bramble.Main()
46 | }
47 | ```
48 |
49 | ## How to
50 |
51 | ### Configure the plugin
52 |
53 | ```go
54 | type MyPluginConfig struct {
55 | // ...
56 | }
57 |
58 | type MyPlugin struct {
59 | config MyPluginConfig
60 | }
61 |
62 | func (p *MyPlugin) Configure(cfg *bramble.Config, data json.RawMessage) error {
63 | // data contains the raw "config" JSON for the plugin
64 | return json.Unmarshal(data, &p.config)
65 | }
66 | ```
67 |
68 | ### Initialize the plugin
69 |
70 | `Init` gives an opportunity to the plugin to access and store a pointer to
71 | the `ExecutableSchema` (contains information about the schema, services...).
72 |
73 | ```go
74 | func (p *MyPlugin) Init(s *bramble.ExecutableSchema) {
75 | // ...
76 | }
77 | ```
78 |
79 | ### Register a new route
80 |
81 | ```go
82 | func (p *MyPlugin) SetupPublicMux(mux *http.ServeMux) {
83 | mux.HandleFunc("/my-new-public-route", newRouteHandler)
84 | }
85 |
86 | func (p *MyPlugin) SetupPrivateMux(mux *http.ServeMux) {
87 | mux.HandleFunc("/my-new-private-route", newRouteHandler)
88 | }
89 |
90 | func newRouteHandler(w http.ResponseWriter, r *http.Request) {
91 | // ...
92 | }
93 | ```
94 |
95 | ### Expose and federate a GraphQL endpoint
96 |
97 | Plugins can also act as federated services. For this use `GraphqlQueryPath`
98 | to return the private route used by your graphql endpoint.
99 |
100 | ```go
101 | func (i *InternalsServicePlugin) GraphqlQueryPath() (bool, string) {
102 | return true, "my-graphql-endpoint"
103 | }
104 |
105 | func (i *InternalsServicePlugin) SetupPrivateMux(mux *http.ServeMux) {
106 | mux.Handle("/my-graphql-endpoint", myGraphqlHandler)
107 | }
108 | ```
109 |
110 | ### Apply a middleware
111 |
112 | ```go
113 | func (p *MyPlugin) ApplyMiddlewarePublicMux(h http.Handler) http.Handler {
114 | // add a timeout to queries
115 | return http.TimeoutHandler(h, 1 * time.Second, "query timeout")
116 | }
117 | ```
118 |
--------------------------------------------------------------------------------
/main.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "flag"
6 | "fmt"
7 | log "log/slog"
8 | "net/http"
9 | "os"
10 | "os/signal"
11 | "sync"
12 | "time"
13 | )
14 |
15 | // Main runs the gateway. This function is exported so that it can be reused
16 | // when building Bramble with custom plugins.
17 | func Main() {
18 | ctx := context.Background()
19 |
20 | var configFiles arrayFlags
21 | level := new(log.LevelVar)
22 | flag.Var(&configFiles, "config", "Config file (can appear multiple times)")
23 | flag.Var(&configFiles, "conf", "deprecated, use -config instead")
24 | flag.TextVar(level, "loglevel", level, "log level: debug, info, warn, error")
25 | flag.Parse()
26 |
27 | logger := log.New(log.NewJSONHandler(os.Stderr, &log.HandlerOptions{Level: level}))
28 | log.SetDefault(logger)
29 |
30 | cfg, err := GetConfig(configFiles)
31 | if err != nil {
32 | log.With("error", err).Error("failed to load config")
33 | os.Exit(1)
34 | }
35 | go cfg.Watch()
36 |
37 | shutdown, err := InitTelemetry(ctx, cfg.Telemetry)
38 | if err != nil {
39 | log.With("error", err).Error("failed initializing telemetry")
40 | }
41 |
42 | defer func() {
43 | log.Info("flushing and shutting down telemetry")
44 | if err := shutdown(context.Background()); err != nil {
45 | log.With("error", err).Error("shutting down telemetry")
46 | }
47 | }()
48 |
49 | err = cfg.Init()
50 | if err != nil {
51 | log.With("error", err).Error("failed to configure")
52 | os.Exit(1)
53 | }
54 |
55 | log.With("config", cfg).Debug("configuration")
56 |
57 | gtw := NewGateway(cfg.executableSchema, cfg.plugins)
58 | RegisterMetrics()
59 |
60 | go gtw.UpdateSchemas(cfg.PollIntervalDuration)
61 |
62 | ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
63 | defer cancel()
64 |
65 | var wg sync.WaitGroup
66 | wg.Add(3)
67 |
68 | go runHandler(ctx, &wg, "metrics", cfg.MetricAddress(), cfg.DefaultTimeouts, NewMetricsHandler())
69 | go runHandler(ctx, &wg, "private", cfg.PrivateAddress(), cfg.PrivateTimeouts, gtw.PrivateRouter())
70 | go runHandler(ctx, &wg, "public", cfg.GatewayAddress(), cfg.GatewayTimeouts, gtw.Router(cfg))
71 |
72 | wg.Wait()
73 | }
74 |
75 | func runHandler(ctx context.Context, wg *sync.WaitGroup, name, addr string, timeouts TimeoutConfig, handler http.Handler) {
76 | srv := &http.Server{
77 | Addr: addr,
78 | Handler: handler,
79 | ReadTimeout: timeouts.ReadTimeoutDuration,
80 | WriteTimeout: timeouts.WriteTimeoutDuration,
81 | IdleTimeout: timeouts.IdleTimeoutDuration,
82 | }
83 |
84 | go func() {
85 | log.With("addr", addr).Info(fmt.Sprintf("serving %s handler", name))
86 | if err := srv.ListenAndServe(); err != http.ErrServerClosed {
87 | log.With("error", err).Error("server terminated unexpectedly")
88 | os.Exit(1)
89 | }
90 | }()
91 |
92 | <-ctx.Done()
93 |
94 | timeoutCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
95 | defer cancel()
96 |
97 | log.Info(fmt.Sprintf("shutting down %s handler", name))
98 | err := srv.Shutdown(timeoutCtx)
99 | if err != nil {
100 | log.With("error", err).Error("failed shutting down server")
101 | }
102 | log.Info(fmt.Sprintf("shut down %s handler", name))
103 | wg.Done()
104 | }
105 |
--------------------------------------------------------------------------------
/plugins/admin_ui.go:
--------------------------------------------------------------------------------
1 | package plugins
2 |
3 | import (
4 | "bytes"
5 | _ "embed"
6 | "errors"
7 | "html/template"
8 | log "log/slog"
9 | "net/http"
10 | "os"
11 | "sort"
12 |
13 | "github.com/vektah/gqlparser/v2"
14 | "github.com/vektah/gqlparser/v2/ast"
15 | "github.com/vektah/gqlparser/v2/formatter"
16 |
17 | "github.com/movio/bramble"
18 | )
19 |
20 | func init() {
21 | bramble.RegisterPlugin(&AdminUIPlugin{})
22 | }
23 |
24 | // AdminUIPlugin serves a minimal administration interface.
25 | type AdminUIPlugin struct {
26 | bramble.BasePlugin
27 | executableSchema *bramble.ExecutableSchema
28 | template *template.Template
29 | }
30 |
31 | func (p *AdminUIPlugin) ID() string {
32 | return "admin-ui"
33 | }
34 |
35 | func (p *AdminUIPlugin) Init(s *bramble.ExecutableSchema) {
36 | tmpl := template.New("admin")
37 | _, err := tmpl.Parse(htmlTemplate)
38 | if err != nil {
39 | log.With("error", err).Error("unable to load admin UI page template")
40 | os.Exit(1)
41 | }
42 |
43 | p.template = tmpl
44 | p.executableSchema = s
45 | }
46 |
47 | func (p *AdminUIPlugin) SetupPrivateMux(mux *http.ServeMux) {
48 | mux.HandleFunc("/admin", p.handler)
49 | }
50 |
51 | type services []service
52 |
53 | func (s services) Len() int {
54 | return len(s)
55 | }
56 |
57 | func (s services) Less(i, j int) bool {
58 | return s[i].Name < s[j].Name
59 | }
60 |
61 | func (s services) Swap(i, j int) {
62 | s[i], s[j] = s[j], s[i]
63 | }
64 |
65 | type service struct {
66 | Name string
67 | Version string
68 | ServiceURL string
69 | Schema string
70 | Status string
71 | }
72 |
73 | type templateVariables struct {
74 | TestedSchema string
75 | TestSchemaResult string
76 | TestSchemaError string
77 | Services services
78 | }
79 |
80 | func (p *AdminUIPlugin) handler(w http.ResponseWriter, r *http.Request) {
81 | var vars templateVariables
82 |
83 | if testSchema := r.FormValue("schema"); testSchema != "" {
84 | vars.TestedSchema = testSchema
85 | resultSchema, err := p.testSchema(testSchema)
86 | vars.TestSchemaResult = resultSchema
87 | if err != nil {
88 | vars.TestSchemaError = err.Error()
89 | }
90 | }
91 |
92 | for _, s := range p.executableSchema.Services {
93 | vars.Services = append(vars.Services, service{
94 | Name: s.Name,
95 | Version: s.Version,
96 | ServiceURL: s.ServiceURL,
97 | Schema: s.SchemaSource,
98 | Status: s.Status,
99 | })
100 | }
101 |
102 | sort.Sort(vars.Services)
103 |
104 | _ = p.template.Execute(w, vars)
105 | }
106 |
107 | func (p *AdminUIPlugin) testSchema(schemaStr string) (string, error) {
108 | schema, gqlErr := gqlparser.LoadSchema(&ast.Source{Input: schemaStr})
109 | if gqlErr != nil {
110 | return "", errors.New(gqlErr.Error())
111 | }
112 |
113 | if err := bramble.ValidateSchema(schema); err != nil {
114 | return "", err
115 | }
116 |
117 | schemas := []*ast.Schema{schema}
118 | for _, service := range p.executableSchema.Services {
119 | schemas = append(schemas, service.Schema)
120 | }
121 |
122 | result, err := bramble.MergeSchemas(schemas...)
123 | if err != nil {
124 | return "", err
125 | }
126 |
127 | var buf bytes.Buffer
128 | f := formatter.NewFormatter(&buf)
129 | f.FormatSchema(result)
130 |
131 | return buf.String(), nil
132 | }
133 |
134 | //go:embed admin_ui.html.template
135 | var htmlTemplate string
136 |
--------------------------------------------------------------------------------
/testsrv/gadget_test_server.go:
--------------------------------------------------------------------------------
1 | package testsrv
2 |
3 | import (
4 | "errors"
5 | "net/http/httptest"
6 |
7 | "github.com/graph-gophers/graphql-go"
8 | "github.com/graph-gophers/graphql-go/relay"
9 | )
10 |
11 | type gizmoWithGadgetResolver struct {
12 | IDField string
13 | Gadget *gadgetResolver
14 | }
15 |
16 | func (u gizmoWithGadgetResolver) ID() graphql.ID {
17 | return graphql.ID(u.IDField)
18 | }
19 |
20 | type gadgetServiceResolver struct {
21 | serviceField service
22 | }
23 |
24 | func (g *gadgetServiceResolver) Service() service {
25 | return g.serviceField
26 | }
27 |
28 | func (g *gadgetServiceResolver) BoundaryGizmo(args struct{ ID string }) (*gizmoWithGadgetResolver, error) {
29 | gadget, ok := gadgetMap[args.ID]
30 | if !ok {
31 | return nil, errors.New("gadget not found")
32 | }
33 | return &gizmoWithGadgetResolver{
34 | IDField: args.ID,
35 | Gadget: &gadgetResolver{gadget},
36 | }, nil
37 | }
38 |
39 | type gadget interface {
40 | ID() graphql.ID
41 | Name() string
42 | }
43 |
44 | type gadgetResolver struct {
45 | gadget
46 | }
47 |
48 | var gadgetMap = map[string]gadget{
49 | "GIZMO1": &jetpack{
50 | IDField: "JETPACK1",
51 | NameField: "Jetpack #1",
52 | RangeField: "500km",
53 | },
54 | "GIZMO2": &invisibleCar{
55 | IDField: "AM1",
56 | NameField: "Vanquish",
57 | CloakedField: true,
58 | },
59 | }
60 |
61 | type jetpack struct {
62 | IDField string
63 | NameField string
64 | RangeField string
65 | }
66 |
67 | func (r *gadgetResolver) ToJetpack() (*jetpack, bool) {
68 | jetpack, ok := r.gadget.(*jetpack)
69 | return jetpack, ok
70 | }
71 |
72 | func (j jetpack) ID() graphql.ID {
73 | return graphql.ID(j.IDField)
74 | }
75 |
76 | func (j jetpack) Name() string {
77 | return j.NameField
78 | }
79 |
80 | func (j jetpack) Range() string {
81 | return j.RangeField
82 | }
83 |
84 | type invisibleCar struct {
85 | IDField string
86 | NameField string
87 | CloakedField bool
88 | }
89 |
90 | func (r *gadgetResolver) ToInvisibleCar() (*invisibleCar, bool) {
91 | invisableCar, ok := r.gadget.(*invisibleCar)
92 | return invisableCar, ok
93 | }
94 |
95 | func (j invisibleCar) ID() graphql.ID {
96 | return graphql.ID(j.IDField)
97 | }
98 |
99 | func (j invisibleCar) Name() string {
100 | return j.NameField
101 | }
102 |
103 | func (j invisibleCar) Cloaked() bool {
104 | return j.CloakedField
105 | }
106 |
107 | func NewGadgetService() *httptest.Server {
108 | s := `
109 | directive @boundary on OBJECT | FIELD_DEFINITION
110 |
111 | type Query {
112 | service: Service!
113 | boundaryGizmo(id: ID!): Gizmo @boundary
114 | }
115 |
116 | type Gizmo @boundary {
117 | id: ID!
118 | gadget: Gadget
119 | }
120 |
121 | interface Gadget {
122 | id: ID!
123 | name: String!
124 | }
125 |
126 | type Jetpack implements Gadget {
127 | id: ID!
128 | name: String!
129 | range: String!
130 | }
131 |
132 | type InvisibleCar implements Gadget {
133 | id: ID!
134 | name: String!
135 | cloaked: Boolean!
136 | }
137 |
138 | type Service {
139 | name: String!
140 | version: String!
141 | schema: String!
142 | }`
143 |
144 | schema := graphql.MustParseSchema(s, &gadgetServiceResolver{
145 | serviceField: service{
146 | Name: "gadget-service",
147 | Version: "v0.0.1",
148 | Schema: s,
149 | },
150 | }, graphql.UseFieldResolvers())
151 |
152 | return httptest.NewServer(&relay.Handler{Schema: schema})
153 | }
154 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | 
2 |
3 | [](https://pkg.go.dev/github.com/movio/bramble)
4 | [](https://goreportcard.com/report/github.com/movio/bramble)
5 | [](https://codecov.io/gh/movio/bramble)
6 |
7 | [**Full documentation**](https://movio.github.io/bramble)
8 |
9 | Bramble is a production-ready GraphQL federation gateway.
10 | It is built to be a simple, reliable and scalable way to aggregate GraphQL services together.
11 |
12 | 
13 |
14 | ## Features
15 |
16 | Bramble supports:
17 |
18 | - Shared types across services
19 | - Namespaces
20 | - Field-level permissions
21 | - Plugins:
22 | - JWT, CORS, ...
23 | - Or add your own
24 | - Hot reloading of configuration
25 |
26 | It is also stateless and scales very easily.
27 |
28 | ## Future work/not currently supported
29 |
30 | There is currently no support for:
31 |
32 | - Subscriptions
33 | - Shared unions, interfaces, scalars, enums or inputs across services
34 |
35 | Check FAQ for details: https://movio.github.io/bramble/#/federation?id=restriction-on-subscription
36 |
37 | ## Contributing
38 |
39 | Contributions are always welcome!
40 |
41 | If you wish to contribute please open a pull request. Please make sure to:
42 |
43 | - include a brief description or link to the relevant issue
44 | - (if applicable) add tests for the behaviour you're adding/modifying
45 | - commit messages are descriptive
46 |
47 | Before making a significant change we recommend opening an issue to discuss
48 | the issue you're facing and the proposed solution.
49 |
50 | ### Building and testing
51 |
52 | Prerequisite: Go 1.23 or newer
53 |
54 | To build the `bramble` command:
55 |
56 | ```bash
57 | go build -o bramble ./cmd/bramble
58 | ./bramble -config config.json
59 | ```
60 |
61 | To run the tests:
62 |
63 | ```bash
64 | go test ./...
65 | ```
66 |
67 | # Running locally
68 |
69 | There is a [docker-compose](./docker-compose.yaml) file that will run bramble and three [example](./examples) services.
70 |
71 | ```
72 | docker-compose up
73 | ```
74 |
75 | The gateway will then be hosted on `http://localhost:8082/query`, be sure to point a GraphQL client to this address.
76 |
77 | ```graphql
78 | {
79 | randomFoo {
80 | nodejs
81 | graphGophers
82 | gqlgen
83 | }
84 | }
85 | ```
86 |
87 | ## Comparison with other projects
88 |
89 | - [Apollo Server](https://www.apollographql.com/)
90 |
91 | While Apollo Server is a popular tool we felt is was not the right tool for us as:
92 |
93 | - the federation specification is more complex than necessary
94 | - it is written in NodeJS where we favour Go
95 |
96 | - [Nautilus](https://github.com/nautilus/gateway)
97 |
98 | Nautilus provided a lot of inspiration for Bramble.
99 |
100 | Although the approach to federation was initially similar, Bramble now uses
101 | a different approach and supports for a few more things:
102 | fine-grained permissions, namespaces, easy plugin configuration,
103 | configuration hot-reloading...
104 |
105 | Bramble is also a central piece of software for [Movio](https://movio.co)
106 | products and thus is actively maintained and developed.
107 |
--------------------------------------------------------------------------------
/instrumentation_test.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "encoding/json"
6 | "io"
7 | log "log/slog"
8 | "sync"
9 | "testing"
10 | "time"
11 |
12 | "github.com/stretchr/testify/assert"
13 | )
14 |
15 | // can only run one test at a time that takes over the log output
16 | var logLock = sync.Mutex{}
17 |
18 | func collectLogEvent(t *testing.T, o *log.HandlerOptions, f func()) map[string]interface{} {
19 | t.Helper()
20 | r, w := io.Pipe()
21 | defer r.Close()
22 | prevlogger := log.Default()
23 | logLock.Lock()
24 | defer logLock.Unlock()
25 | log.SetDefault(log.New(log.NewJSONHandler(w, o)))
26 | t.Cleanup(func() {
27 | logLock.Lock()
28 | defer logLock.Unlock()
29 | log.SetDefault(prevlogger)
30 | })
31 |
32 | go func() {
33 | defer w.Close()
34 | f()
35 | }()
36 |
37 | var obj map[string]interface{}
38 | err := json.NewDecoder(r).Decode(&obj)
39 | assert.NoError(t, err)
40 |
41 | return obj
42 | }
43 |
44 | func collectEventFromContext(ctx context.Context, t *testing.T, o *log.HandlerOptions, f func(*event)) map[string]interface{} {
45 | t.Helper()
46 | return collectLogEvent(t, o, func() {
47 | e := getEvent(ctx)
48 | f(e)
49 | if e != nil {
50 | e.finish()
51 | }
52 | })
53 | }
54 |
55 | func testEventName(EventFields) string {
56 | return "test"
57 | }
58 |
59 | func TestDropsField(t *testing.T) {
60 | AddField(context.TODO(), "val", "test")
61 | assert.True(t, true)
62 | }
63 |
64 | func TestEventLogOnFinish(t *testing.T) {
65 | ctx, _ := startEvent(context.TODO(), testEventName)
66 | output := collectEventFromContext(ctx, t, nil, func(*event) {
67 | AddField(ctx, "val", "test")
68 | })
69 |
70 | assert.Equal(t, "test", output["val"])
71 | }
72 |
73 | func TestAddMultipleToEventOnContext(t *testing.T) {
74 | ctx, _ := startEvent(context.TODO(), testEventName)
75 | output := collectEventFromContext(ctx, t, nil, func(*event) {
76 | AddFields(ctx, EventFields{
77 | "gizmo": "foo",
78 | "gimmick": "bar",
79 | })
80 | })
81 |
82 | assert.Equal(t, "foo", output["gizmo"])
83 | assert.Equal(t, "bar", output["gimmick"])
84 | }
85 |
86 | func TestEventMeasurement(t *testing.T) {
87 | start := time.Now()
88 | ctx, _ := startEvent(context.TODO(), testEventName)
89 | output := collectEventFromContext(ctx, t, nil, func(*event) {
90 | time.Sleep(time.Microsecond)
91 | })
92 |
93 | if ts, ok := output["time"].(string); ok {
94 | timestamp, err := time.Parse(time.RFC3339Nano, ts)
95 | assert.NoError(t, err)
96 | assert.WithinDuration(t, start, timestamp, time.Second)
97 | } else {
98 | assert.Fail(t, "missing timestamp")
99 | }
100 | if dur, ok := output["duration"].(string); ok {
101 | duration, err := time.ParseDuration(dur)
102 | assert.NoError(t, err)
103 | assert.True(t, duration > 0)
104 | } else {
105 | assert.Fail(t, "missing duration")
106 | }
107 | }
108 |
109 | func TestDebugDisabled(t *testing.T) {
110 | ctx, _ := startEvent(context.TODO(), testEventName)
111 |
112 | o := &log.HandlerOptions{
113 | Level: log.LevelInfo,
114 | }
115 |
116 | output := collectEventFromContext(ctx, t, o, func(e *event) {
117 | if e.debugEnabled() {
118 | AddField(ctx, "val", "test")
119 | }
120 | })
121 |
122 | assert.Empty(t, output["val"])
123 | }
124 |
125 | func TestDebugEnabled(t *testing.T) {
126 | ctx, _ := startEvent(context.TODO(), testEventName)
127 |
128 | o := &log.HandlerOptions{
129 | Level: log.LevelDebug,
130 | }
131 |
132 | output := collectEventFromContext(ctx, t, o, func(e *event) {
133 | if e.debugEnabled() {
134 | AddField(ctx, "val", "test")
135 | }
136 | })
137 |
138 | assert.Equal(t, "test", output["val"])
139 | }
140 |
--------------------------------------------------------------------------------
/docs/configuration.md:
--------------------------------------------------------------------------------
1 | # Configuration
2 |
3 | Bramble can be configured by passing one or more JSON config file with the `-config` parameter.
4 |
5 | Config files are also hot-reloaded on change (see below for list of supported options).
6 |
7 | Sample configuration:
8 |
9 | ```json
10 | {
11 | "services": ["http://service1/query", "http://service2/query"],
12 | "gateway-port": 8082,
13 | "private-port": 8083,
14 | "metrics-port": 9009,
15 | "log-level": "info",
16 | "poll-interval": "5s",
17 | "max-requests-per-query": 50,
18 | "max-client-response-size": 1048576,
19 | "id-field-name": "id",
20 | "telemetry": {
21 | "enabled": true,
22 | "insecure": false,
23 | "endpoint": "http://localhost:4317",
24 | "serviceName": "bramble"
25 | },
26 | "plugins": [
27 | {
28 | "name": "admin-ui"
29 | },
30 | {
31 | "name": "my-plugin",
32 | "config": {
33 | ...
34 | }
35 | }
36 | ],
37 | "extensions": {
38 | ...
39 | }
40 | }
41 | ```
42 |
43 | - `services`: URLs of services to federate.
44 |
45 | - **Required**
46 | - Supports hot-reload: Yes
47 | - Configurable also by `BRAMBLE_SERVICE_LIST` environment variable set to a space separated list of urls which will be appended to the list
48 |
49 | - `gateway-port`: public port for the gateway, this is where the query endpoint
50 | is exposed. Plugins can expose additional endpoints on this port.
51 |
52 | - Default: 8082
53 | - Supports hot-reload: No
54 |
55 | - `private-port`: A port for plugins to expose private endpoints. Not used by default.
56 |
57 | - Default: 8083
58 | - Supports hot-reload: No
59 |
60 | - `metrics-port`: Port used to expose Prometheus metrics.
61 |
62 | - Default: 9009
63 | - Supports hot-reload: No
64 |
65 | - `log-level`: Log level, one of `debug`|`info`|`error`|`fatal`.
66 |
67 | - Default: `debug`
68 | - Supports hot-reload: Yes
69 |
70 | - `poll-interval`: Interval at which federated services are polled (`service` query is called).
71 |
72 | - Default: `5s`
73 | - Supports hot-reload: No
74 |
75 | - `max-requests-per-query`: Maximum number of requests to federated services
76 | a single query to Bramble can generate. For example, a query requesting
77 | fields from two different services might generate two or more requests to
78 | federated services.
79 |
80 | - Default: 50
81 | - Supports hot-reload: No
82 |
83 | - `max-service-response-size`: The max response size that Bramble can receive from federated services
84 |
85 | - Default: 1MB
86 | - Supports hot-reload: No
87 |
88 | - `id-field-name`: Optional customisation of the field name used to cross-reference boundary types.
89 |
90 | - Default: `id`
91 | - Supports hot-reload: No
92 |
93 | - `telemetry`: OpenTelemetry configuration.
94 | - `enabled`: Enable OpenTelemetry.
95 | - Default: `false`
96 | - Supports hot-reload: No
97 | - `insecure`: Whether to use insecure connection to OpenTelemetry collector.
98 | - Default: `false`
99 | - Supports hot-reload: No
100 | - `endpoint`: OpenTelemetry collector endpoint.
101 | - Default: If no endpoint is specified, telemetry is disabled. Bramble will check for `BRAMBLE_OTEL_ENDPOINT` environment variable and use it if set.
102 | - Supports hot-reload: No
103 | - `serviceName`: Service name to use for OpenTelemetry.
104 | - Default: `bramble`
105 | - Supports hot-reload: No
106 |
107 |
108 | - `plugins`: Optional list of plugins to enable. See [plugins](plugins.md) for plugins-specific config.
109 |
110 | - Supports hot-reload: Partial. `Configure` method of previously enabled plugins will get called with new configuration.
111 |
112 | - `extensions`: Non-standard configuration, can be used to share configuration across plugins.
113 |
--------------------------------------------------------------------------------
/metrics.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "net/http"
5 | "net/http/pprof"
6 |
7 | "github.com/prometheus/client_golang/prometheus"
8 | "github.com/prometheus/client_golang/prometheus/promhttp"
9 | )
10 |
11 | var (
12 | // promInvalidSchema is a gauge representing the current status of remote services schemas
13 | promInvalidSchema = prometheus.NewGauge(prometheus.GaugeOpts{
14 | Name: "invalid_schema",
15 | Help: "A gauge representing the current status of remote services schemas",
16 | })
17 |
18 | promServiceUpdateErrorCounter = prometheus.NewCounterVec(
19 | prometheus.CounterOpts{
20 | Name: "service_update_error_total",
21 | Help: "A counter indicating how many times services have failed to update",
22 | },
23 | []string{
24 | "service",
25 | },
26 | )
27 |
28 | promServiceTimeoutErrorCounter = prometheus.NewCounterVec(
29 | prometheus.CounterOpts{
30 | Name: "service_timeout_error_total",
31 | Help: "A counter indicating how many times services have timed out",
32 | },
33 | []string{
34 | "service",
35 | },
36 | )
37 |
38 | promServiceUpdateErrorGauge = prometheus.NewGaugeVec(
39 | prometheus.GaugeOpts{
40 | Name: "service_update_error",
41 | Help: "A gauge indicating what services are failing to update",
42 | },
43 | []string{
44 | "service",
45 | },
46 | )
47 |
48 | // promHTTPInFlightGauge is a gauge of requests currently being served by the wrapped handler
49 | promHTTPInFlightGauge = prometheus.NewGauge(prometheus.GaugeOpts{
50 | Name: "http_in_flight_requests",
51 | Help: "A gauge of requests currently being served",
52 | })
53 |
54 | // promHTTPRequestCounter is a counter for requests to the wrapped handler
55 | promHTTPRequestCounter = prometheus.NewCounterVec(
56 | prometheus.CounterOpts{
57 | Name: "http_api_requests_total",
58 | Help: "A counter for served requests",
59 | },
60 | []string{"code"},
61 | )
62 |
63 | // promHTTPResponseDurations is a histogram of request latencies
64 | promHTTPResponseDurations = prometheus.NewHistogramVec(
65 | prometheus.HistogramOpts{
66 | Name: "http_response_duration_seconds",
67 | Help: "A histogram of request latencies",
68 | Buckets: prometheus.DefBuckets,
69 | },
70 | []string{},
71 | )
72 |
73 | // promHTTPRequestSizes is a histogram of request sizes for requests
74 | promHTTPRequestSizes = prometheus.NewHistogramVec(
75 | prometheus.HistogramOpts{
76 | Name: "http_request_size_bytes",
77 | Help: "A histogram of request sizes for requests",
78 | Buckets: prometheus.ExponentialBuckets(128, 2, 10),
79 | },
80 | []string{},
81 | )
82 |
83 | // promHTTPResponseSizes is a histogram of response sizes for responses.
84 | promHTTPResponseSizes = prometheus.NewHistogramVec(
85 | prometheus.HistogramOpts{
86 | Name: "http_response_size_bytes",
87 | Help: "A histogram of response sizes for responses",
88 | Buckets: prometheus.ExponentialBuckets(1024, 2, 10),
89 | },
90 | []string{},
91 | )
92 | )
93 |
94 | // RegisterMetrics register the prometheus metrics.
95 | func RegisterMetrics() {
96 | prometheus.MustRegister(promInvalidSchema)
97 | prometheus.MustRegister(promServiceTimeoutErrorCounter)
98 | prometheus.MustRegister(promServiceUpdateErrorCounter)
99 | prometheus.MustRegister(promServiceUpdateErrorGauge)
100 | prometheus.MustRegister(promHTTPInFlightGauge)
101 | prometheus.MustRegister(promHTTPRequestCounter)
102 | prometheus.MustRegister(promHTTPResponseDurations)
103 | prometheus.MustRegister(promHTTPRequestSizes)
104 | prometheus.MustRegister(promHTTPResponseSizes)
105 | }
106 |
107 | // NewMetricsHandler returns a new Prometheus metrics handler.
108 | func NewMetricsHandler() http.Handler {
109 | mux := http.NewServeMux()
110 | mux.Handle("/metrics", promhttp.Handler())
111 | mux.HandleFunc("/debug/pprof/", pprof.Index)
112 |
113 | return mux
114 | }
115 |
--------------------------------------------------------------------------------
/server_test.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "testing"
6 |
7 | "github.com/movio/bramble/testsrv"
8 | "github.com/stretchr/testify/require"
9 | "github.com/vektah/gqlparser/v2"
10 | )
11 |
12 | func TestFederatedQuery(t *testing.T) {
13 | gizmoService := testsrv.NewGizmoService()
14 | gadgetService := testsrv.NewGadgetService()
15 |
16 | executableSchema := NewExecutableSchema(nil, 10, nil, NewService(gizmoService.URL), NewService(gadgetService.URL))
17 |
18 | require.NoError(t, executableSchema.UpdateSchema(context.TODO(), true))
19 |
20 | query := gqlparser.MustLoadQuery(executableSchema.MergedSchema, `{
21 | gizmo(id: "GIZMO1") {
22 | id
23 | name
24 | }
25 | }`)
26 |
27 | ctx := testContextWithoutVariables(query.Operations[0])
28 |
29 | response := executableSchema.ExecuteQuery(ctx)
30 | expectedResponse := `
31 | {
32 | "gizmo": {
33 | "id": "GIZMO1",
34 | "name": "Gizmo #1"
35 | }
36 | }
37 | `
38 | jsonEqWithOrder(t, expectedResponse, string(response.Data))
39 | gizmoService.Close()
40 | gadgetService.Close()
41 | }
42 |
43 | func TestFederatedQueryWithMultipleFragmentSpreads(t *testing.T) {
44 | gizmoService := testsrv.NewGizmoService()
45 | gadgetService := testsrv.NewGadgetService()
46 |
47 | executableSchema := NewExecutableSchema(nil, 10, nil, NewService(gizmoService.URL), NewService(gadgetService.URL))
48 |
49 | require.NoError(t, executableSchema.UpdateSchema(context.TODO(), true))
50 |
51 | t.Run("first fragment matches", func(t *testing.T) {
52 | query := gqlparser.MustLoadQuery(executableSchema.MergedSchema, `{
53 | gizmo(id: "GIZMO1") {
54 | id
55 | name
56 | gadget {
57 | id
58 | name
59 | ... on Jetpack {
60 | range
61 | }
62 | ... on InvisibleCar {
63 | cloaked
64 | }
65 | }
66 | }
67 | }`)
68 |
69 | ctx := testContextWithoutVariables(query.Operations[0])
70 |
71 | response := executableSchema.ExecuteQuery(ctx)
72 | expectedResponse := `
73 | {
74 | "gizmo": {
75 | "id": "GIZMO1",
76 | "name": "Gizmo #1",
77 | "gadget": {
78 | "id": "JETPACK1",
79 | "name": "Jetpack #1",
80 | "range": "500km"
81 | }
82 | }
83 | }`
84 |
85 | jsonEqWithOrder(t, expectedResponse, string(response.Data))
86 | })
87 |
88 | t.Run("second fragment matches", func(t *testing.T) {
89 | query := gqlparser.MustLoadQuery(executableSchema.MergedSchema, `{
90 | gizmo(id: "GIZMO2") {
91 | id
92 | name
93 | gadget {
94 | id
95 | name
96 | ... on Jetpack {
97 | range
98 | }
99 | ... on InvisibleCar {
100 | cloaked
101 | }
102 | }
103 | }
104 | }`)
105 |
106 | ctx := testContextWithoutVariables(query.Operations[0])
107 |
108 | response := executableSchema.ExecuteQuery(ctx)
109 | expectedResponse := `
110 | {
111 | "gizmo": {
112 | "id": "GIZMO2",
113 | "name": "Gizmo #2",
114 | "gadget": {
115 | "id": "AM1",
116 | "name": "Vanquish",
117 | "cloaked": true
118 | }
119 | }
120 | }`
121 |
122 | jsonEqWithOrder(t, expectedResponse, string(response.Data))
123 | })
124 |
125 | t.Run("no fragments match", func(t *testing.T) {
126 | query := gqlparser.MustLoadQuery(executableSchema.MergedSchema, `{
127 | gizmo(id: "GIZMO2") {
128 | id
129 | name
130 | gadget {
131 | id
132 | name
133 | ... on Jetpack {
134 | range
135 | }
136 | }
137 | }
138 | }`)
139 |
140 | ctx := testContextWithoutVariables(query.Operations[0])
141 |
142 | response := executableSchema.ExecuteQuery(ctx)
143 | expectedResponse := `
144 | {
145 | "gizmo": {
146 | "id": "GIZMO2",
147 | "name": "Gizmo #2",
148 | "gadget": {
149 | "id": "AM1",
150 | "name": "Vanquish"
151 | }
152 | }
153 | }`
154 |
155 | jsonEqWithOrder(t, expectedResponse, string(response.Data))
156 | })
157 |
158 | gizmoService.Close()
159 | gadgetService.Close()
160 | }
161 |
--------------------------------------------------------------------------------
/plugin.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "encoding/json"
6 | log "log/slog"
7 | "net/http"
8 | "os"
9 |
10 | "github.com/99designs/gqlgen/graphql"
11 | "github.com/99designs/gqlgen/graphql/handler"
12 | )
13 |
14 | // Plugin is a Bramble plugin. Plugins can be used to extend base Bramble functionalities.
15 | type Plugin interface {
16 | // ID must return the plugin identifier (name). This is the id used to match
17 | // the plugin in the configuration.
18 | ID() string
19 | // Configure is called during initialization and every time the config is modified.
20 | // The pluginCfg argument is the raw json contained in the "config" key for that plugin.
21 | Configure(cfg *Config, pluginCfg json.RawMessage) error
22 | // Init is called once on initialization
23 | Init(schema *ExecutableSchema)
24 | SetupPublicMux(mux *http.ServeMux)
25 | SetupGatewayHandler(handler *handler.Server)
26 | SetupPrivateMux(mux *http.ServeMux)
27 | // Should return true and the query path if the plugin is a service that
28 | // should be federated by Bramble
29 | GraphqlQueryPath() (bool, string)
30 | ApplyMiddlewarePublicMux(http.Handler) http.Handler
31 | ApplyMiddlewarePrivateMux(http.Handler) http.Handler
32 | WrapGraphQLClientTransport(http.RoundTripper) http.RoundTripper
33 |
34 | InterceptRequest(ctx context.Context, operationName, rawQuery string, variables map[string]interface{})
35 | InterceptResponse(ctx context.Context, operationName, rawQuery string, variables map[string]interface{}, response *graphql.Response) *graphql.Response
36 | }
37 |
38 | // BasePlugin is an empty plugin. It can be embedded by any plugin as a way to avoid
39 | // declaring unnecessary methods.
40 | type BasePlugin struct{}
41 |
42 | // Configure ...
43 | func (p *BasePlugin) Configure(*Config, json.RawMessage) error {
44 | return nil
45 | }
46 |
47 | // Init ...
48 | func (p *BasePlugin) Init(s *ExecutableSchema) {}
49 |
50 | func (p *BasePlugin) SetupGatewayHandler(handler *handler.Server) {}
51 |
52 | // SetupPublicMux ...
53 | func (p *BasePlugin) SetupPublicMux(mux *http.ServeMux) {}
54 |
55 | // SetupPrivateMux ...
56 | func (p *BasePlugin) SetupPrivateMux(mux *http.ServeMux) {}
57 |
58 | // GraphqlQueryPath ...
59 | func (p *BasePlugin) GraphqlQueryPath() (bool, string) {
60 | return false, ""
61 | }
62 |
63 | // InterceptRequest is called before bramble starts executing a request.
64 | // It can be used to inspect the unmarshalled GraphQL request bramble receives.
65 | func (p *BasePlugin) InterceptRequest(ctx context.Context, operationName, rawQuery string, variables map[string]interface{}) {
66 | }
67 |
68 | // InterceptResponse is called after bramble has finished executing a request.
69 | // It can be used to inspect and/or modify the response bramble will return.
70 | func (p *BasePlugin) InterceptResponse(ctx context.Context, operationName, rawQuery string, variables map[string]interface{}, response *graphql.Response) *graphql.Response {
71 | return response
72 | }
73 |
74 | // ApplyMiddlewarePublicMux ...
75 | func (p *BasePlugin) ApplyMiddlewarePublicMux(h http.Handler) http.Handler {
76 | return h
77 | }
78 |
79 | // ApplyMiddlewarePrivateMux ...
80 | func (p *BasePlugin) ApplyMiddlewarePrivateMux(h http.Handler) http.Handler {
81 | return h
82 | }
83 |
84 | // WrapGraphQLClientTransport wraps the http.RoundTripper used for GraphQL requests.
85 | func (p *BasePlugin) WrapGraphQLClientTransport(transport http.RoundTripper) http.RoundTripper {
86 | return transport
87 | }
88 |
89 | var registeredPlugins = map[string]Plugin{}
90 |
91 | // RegisterPlugin register a plugin so that it can be enabled via the configuration.
92 | func RegisterPlugin(p Plugin) {
93 | if _, found := registeredPlugins[p.ID()]; found {
94 | log.With("plugin", p.ID()).Error("plugin already registered")
95 | os.Exit(1)
96 | }
97 | registeredPlugins[p.ID()] = p
98 | }
99 |
100 | // RegisteredPlugins returned the list of registered plugins.
101 | func RegisteredPlugins() map[string]Plugin {
102 | return registeredPlugins
103 | }
104 |
--------------------------------------------------------------------------------
/docs/logo.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
42 |
--------------------------------------------------------------------------------
/docs/bramble-header.svg:
--------------------------------------------------------------------------------
1 |
2 |
51 |
--------------------------------------------------------------------------------
/middleware.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "bytes"
5 | "context"
6 | "encoding/json"
7 | "fmt"
8 | "io"
9 | "mime"
10 | "net"
11 | "net/http"
12 | "strings"
13 |
14 | "github.com/felixge/httpsnoop"
15 | "github.com/prometheus/client_golang/prometheus"
16 | )
17 |
18 | type middleware func(http.Handler) http.Handler
19 |
20 | // DebugKey is used to request debug info from the context
21 | const DebugKey contextKey = "debug"
22 |
23 | const (
24 | debugHeader = "X-Bramble-Debug"
25 | )
26 |
27 | // DebugInfo contains the requested debug info for a query
28 | type DebugInfo struct {
29 | Variables bool
30 | Query bool
31 | Plan bool
32 | Timing bool
33 | TraceID bool
34 | }
35 |
36 | func debugMiddleware(h http.Handler) http.Handler {
37 | return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
38 | info := DebugInfo{}
39 | for _, field := range strings.Fields(r.Header.Get(debugHeader)) {
40 | switch field {
41 | case "all":
42 | info.Variables = true
43 | info.Plan = true
44 | info.Query = true
45 | info.Timing = true
46 | info.TraceID = true
47 | case "query":
48 | info.Query = true
49 | case "variables":
50 | info.Variables = true
51 | case "plan":
52 | info.Plan = true
53 | case "timing":
54 | info.Timing = true
55 | case "traceid":
56 | info.TraceID = true
57 | }
58 | }
59 |
60 | ctx := context.WithValue(r.Context(), DebugKey, info)
61 | h.ServeHTTP(w, r.WithContext(ctx))
62 | })
63 | }
64 |
65 | func monitoringMiddleware(h http.Handler) http.Handler {
66 | return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
67 | ctx, event := startEvent(r.Context(), nameMonitoringEvent)
68 | if !strings.HasPrefix(r.Header.Get("user-agent"), "Bramble") {
69 | defer event.finish()
70 | }
71 |
72 | if host := r.Header.Get("X-Forwarded-Host"); host != "" {
73 | event.addField("forwarded_host", host)
74 | }
75 |
76 | var buf bytes.Buffer
77 | _, err := io.Copy(&buf, r.Body)
78 | if err != nil {
79 | w.WriteHeader(http.StatusInternalServerError)
80 | return
81 | }
82 | r.Body = io.NopCloser(&buf)
83 |
84 | r = r.WithContext(ctx)
85 |
86 | if event.debugEnabled() {
87 | addRequestBody(event, r, buf)
88 | }
89 |
90 | m := httpsnoop.CaptureMetrics(h, w, r)
91 |
92 | event.addFields(EventFields{
93 | "response.status": m.Code,
94 | "request.path": r.URL.Path,
95 | "response.size": m.Written,
96 | })
97 | if ip, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
98 | event.addField("request.ip", ip)
99 | }
100 |
101 | promHTTPRequestCounter.With(prometheus.Labels{
102 | "code": fmt.Sprintf("%dXX", m.Code/100),
103 | }).Inc()
104 | promHTTPRequestSizes.With(prometheus.Labels{}).Observe(float64(buf.Len()))
105 | promHTTPResponseSizes.With(prometheus.Labels{}).Observe(float64(m.Written))
106 | promHTTPResponseDurations.With(prometheus.Labels{}).Observe(m.Duration.Seconds())
107 | })
108 | }
109 |
110 | func nameMonitoringEvent(fields EventFields) string {
111 | if t := fields["operation.type"]; t != nil {
112 | if n := fields["operation.name"]; n != "" {
113 | return fmt.Sprintf("%s:%s", t, n)
114 | }
115 | return fmt.Sprintf("%s", t)
116 | }
117 | return "request"
118 | }
119 |
120 | func addRequestBody(e *event, r *http.Request, buf bytes.Buffer) {
121 | contentType, _, _ := mime.ParseMediaType(r.Header.Get("Content-Type"))
122 | e.addField("request.content-type", contentType)
123 |
124 | if r.Method != http.MethodHead && r.Method != http.MethodGet {
125 | switch {
126 | case contentType == "application/json":
127 | var payload interface{}
128 | if err := json.Unmarshal(buf.Bytes(), &payload); err == nil {
129 | e.addField("request.body", &payload)
130 | } else {
131 | e.addField("request.body", buf.String())
132 | e.addField("request.error", err)
133 | }
134 | case contentType == "multipart/form-data":
135 | e.addField("request.body", fmt.Sprintf("%d bytes", len(buf.Bytes())))
136 | default:
137 | e.addField("request.body", buf.String())
138 | }
139 | } else {
140 | e.addField("request.body", buf.String())
141 | }
142 | }
143 |
144 | func applyMiddleware(h http.Handler, mws ...middleware) http.Handler {
145 | for _, mw := range mws {
146 | h = mw(h)
147 | }
148 | return h
149 | }
150 |
--------------------------------------------------------------------------------
/examples/gqlgen-multipart-file-upload-service/go.sum:
--------------------------------------------------------------------------------
1 | github.com/99designs/gqlgen v0.17.44 h1:OS2wLk/67Y+vXM75XHbwRnNYJcbuJd4OBL76RX3NQQA=
2 | github.com/99designs/gqlgen v0.17.44/go.mod h1:UTCu3xpK2mLI5qcMNw+HKDiEL77it/1XtAjisC4sLwM=
3 | github.com/agnivade/levenshtein v1.1.1 h1:QY8M92nrzkmr798gCo3kmMyqXFzdQVpxLlGPRBij0P8=
4 | github.com/agnivade/levenshtein v1.1.1/go.mod h1:veldBMzWxcCG2ZvUTKD2kJNRdCk5hVbJomOvKkmgYbo=
5 | github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
6 | github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
7 | github.com/arbovm/levenshtein v0.0.0-20160628152529-48b4e1c0c4d0 h1:jfIu9sQUG6Ig+0+Ap1h4unLjW6YQJpKZVmUzxsD4E/Q=
8 | github.com/arbovm/levenshtein v0.0.0-20160628152529-48b4e1c0c4d0/go.mod h1:t2tdKJDJF9BV14lnkjHmOQgcvEKgtqs5a1N3LNdJhGE=
9 | github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
10 | github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
11 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
12 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
13 | github.com/dgryski/trifles v0.0.0-20200323201526-dd97f9abfb48 h1:fRzb/w+pyskVMQ+UbP35JkH8yB7MYb4q/qhBarqZE6g=
14 | github.com/dgryski/trifles v0.0.0-20200323201526-dd97f9abfb48/go.mod h1:if7Fbed8SFyPtHLHbg49SI7NAdJiC5WIA09pe59rfAA=
15 | github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
16 | github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
17 | github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
18 | github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
19 | github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
20 | github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
21 | github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
22 | github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
23 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
24 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
25 | github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
26 | github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
27 | github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
28 | github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
29 | github.com/sosodev/duration v1.2.0 h1:pqK/FLSjsAADWY74SyWDCjOcd5l7H8GSnnOGEB9A1Us=
30 | github.com/sosodev/duration v1.2.0/go.mod h1:RQIBBX0+fMLc/D9+Jb/fwvVmo0eZvDDEERAikUR6SDg=
31 | github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
32 | github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
33 | github.com/urfave/cli/v2 v2.27.1 h1:8xSQ6szndafKVRmfyeUMxkNUJQMjL1F2zmsZ+qHpfho=
34 | github.com/urfave/cli/v2 v2.27.1/go.mod h1:8qnjx1vcq5s2/wpsqoZFndg2CE5tNFyrTvS6SinrnYQ=
35 | github.com/vektah/gqlparser/v2 v2.5.15 h1:fYdnU8roQniJziV5TDiFPm/Ff7pE8xbVSOJqbsdl88A=
36 | github.com/vektah/gqlparser/v2 v2.5.15/go.mod h1:WQQjFc+I1YIzoPvZBhUQX7waZgg3pMLi0r8KymvAE2w=
37 | github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
38 | github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
39 | golang.org/x/mod v0.14.0 h1:dGoOF9QVLYng8IHTm7BAyWqCqSheQ5pYWGhzW00YJr0=
40 | golang.org/x/mod v0.14.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
41 | golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
42 | golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
43 | golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
44 | golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
45 | golang.org/x/tools v0.17.0 h1:FvmRgNOcs3kOa+T20R1uhfP9F6HgG2mfxDv1vrx1Htc=
46 | golang.org/x/tools v0.17.0/go.mod h1:xsh6VxdV005rRVaS6SSAf9oiAqljS7UZUacMZ8Bnsps=
47 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
48 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
49 | gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
50 | gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
51 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
52 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
53 |
--------------------------------------------------------------------------------
/examples/gqlgen-service/go.sum:
--------------------------------------------------------------------------------
1 | github.com/99designs/gqlgen v0.17.44 h1:OS2wLk/67Y+vXM75XHbwRnNYJcbuJd4OBL76RX3NQQA=
2 | github.com/99designs/gqlgen v0.17.44/go.mod h1:UTCu3xpK2mLI5qcMNw+HKDiEL77it/1XtAjisC4sLwM=
3 | github.com/agnivade/levenshtein v1.1.1 h1:QY8M92nrzkmr798gCo3kmMyqXFzdQVpxLlGPRBij0P8=
4 | github.com/agnivade/levenshtein v1.1.1/go.mod h1:veldBMzWxcCG2ZvUTKD2kJNRdCk5hVbJomOvKkmgYbo=
5 | github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
6 | github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
7 | github.com/arbovm/levenshtein v0.0.0-20160628152529-48b4e1c0c4d0 h1:jfIu9sQUG6Ig+0+Ap1h4unLjW6YQJpKZVmUzxsD4E/Q=
8 | github.com/arbovm/levenshtein v0.0.0-20160628152529-48b4e1c0c4d0/go.mod h1:t2tdKJDJF9BV14lnkjHmOQgcvEKgtqs5a1N3LNdJhGE=
9 | github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
10 | github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
11 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
12 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
13 | github.com/dgryski/trifles v0.0.0-20200323201526-dd97f9abfb48 h1:fRzb/w+pyskVMQ+UbP35JkH8yB7MYb4q/qhBarqZE6g=
14 | github.com/dgryski/trifles v0.0.0-20200323201526-dd97f9abfb48/go.mod h1:if7Fbed8SFyPtHLHbg49SI7NAdJiC5WIA09pe59rfAA=
15 | github.com/go-faker/faker/v4 v4.0.0-beta.3 h1:zjTxJMHn7Po7OCPKY+VjO6mNQ4ZzE7PoBjb2sUNHVPs=
16 | github.com/go-faker/faker/v4 v4.0.0-beta.3/go.mod h1:uuNc0PSRxF8nMgjGrrrU4Nw5cF30Jc6Kd0/FUTTYbhg=
17 | github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
18 | github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
19 | github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
20 | github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
21 | github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
22 | github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
23 | github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
24 | github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
25 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
26 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
27 | github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
28 | github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
29 | github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
30 | github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
31 | github.com/sosodev/duration v1.2.0 h1:pqK/FLSjsAADWY74SyWDCjOcd5l7H8GSnnOGEB9A1Us=
32 | github.com/sosodev/duration v1.2.0/go.mod h1:RQIBBX0+fMLc/D9+Jb/fwvVmo0eZvDDEERAikUR6SDg=
33 | github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
34 | github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
35 | github.com/urfave/cli/v2 v2.27.1 h1:8xSQ6szndafKVRmfyeUMxkNUJQMjL1F2zmsZ+qHpfho=
36 | github.com/urfave/cli/v2 v2.27.1/go.mod h1:8qnjx1vcq5s2/wpsqoZFndg2CE5tNFyrTvS6SinrnYQ=
37 | github.com/vektah/gqlparser/v2 v2.5.15 h1:fYdnU8roQniJziV5TDiFPm/Ff7pE8xbVSOJqbsdl88A=
38 | github.com/vektah/gqlparser/v2 v2.5.15/go.mod h1:WQQjFc+I1YIzoPvZBhUQX7waZgg3pMLi0r8KymvAE2w=
39 | github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
40 | github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
41 | golang.org/x/mod v0.14.0 h1:dGoOF9QVLYng8IHTm7BAyWqCqSheQ5pYWGhzW00YJr0=
42 | golang.org/x/mod v0.14.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
43 | golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
44 | golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
45 | golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
46 | golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
47 | golang.org/x/tools v0.17.0 h1:FvmRgNOcs3kOa+T20R1uhfP9F6HgG2mfxDv1vrx1Htc=
48 | golang.org/x/tools v0.17.0/go.mod h1:xsh6VxdV005rRVaS6SSAf9oiAqljS7UZUacMZ8Bnsps=
49 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
50 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
51 | gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
52 | gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
53 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
54 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
55 |
--------------------------------------------------------------------------------
/docs/plugins.md:
--------------------------------------------------------------------------------
1 | # Plugins
2 |
3 | ## Admin UI
4 |
5 | Admin UI provides a simple administration interface displaying the federated services.
6 |
7 | ```json
8 | {
9 | "name": "admin-ui"
10 | }
11 | ```
12 |
13 | You access the Admin UI by visiting `http://localhost:
40 |
41 | ### Creating a boundary type
42 |
43 | Here are the steps to make a type a boundary type:
44 |
45 | 1. **Add the `@boundary` directive**
46 |
47 | ```graphql
48 | type Movie @boundary {
49 | id: ID!
50 | title: String!
51 | }
52 | ```
53 |
54 | This tells Bramble that the type can be merged with others.
55 |
56 | !> Boundary types must have an `id: ID!` field. This id must be common across services for a given object.
57 |
58 | ?> **A note on boundary types and nullability**59 | As with regular GraphQL types, a null response can sometimes have big 60 | repercussions as a null value will bubble up to the first nullable field.
61 | This is no different with boundary types, so when extending a boundary type 62 | make sure fields are nullable if your service will sometimes return no 63 | response for a given ID. 64 | 65 | 2. **Add and implement boundary queries** 66 | 67 | ```graphql 68 | extend Query { 69 | movie(id: ID!): Movie @boundary 70 | } 71 | ``` 72 | 73 | For Bramble to be able to request an arbitrary boundary object, every service 74 | defining boundary types must also implement a boundary query for each 75 | boundary object. 76 | This query takes exactly one id argument and returns the associated object. 77 | 78 | There are no restrictions on the name of a boundary query or its argument, 79 | only the return type is used to determine the matching boundary object. 80 | 81 | **Array syntax** 82 | 83 | When possible, it's better to batch records by defining the boundary query as an array: 84 | 85 | ```graphql 86 | extend Query { 87 | movies(ids: [ID!]!): [Movie]! @boundary 88 | } 89 | ``` 90 | 91 | With this syntax, Bramble will query multiple IDs as a set instead of requesting 92 | each record individually. This can make services more performant by 93 | reducing the need for dataloaders and lowering the overall query complexity. 94 | 95 | There are again no restrictions on the name of the boundary query or its argument. 96 | The resulting array expects to be a _mapped set_ matching the input length and order, 97 | with any missing records padded by null values. 98 | 99 | _Bramble query with regular boundary query_ 100 | 101 | ```graphql 102 | { 103 | _0: movie(id: "1") { 104 | id 105 | title 106 | } 107 | _1: movie(id: "2") { 108 | id 109 | title 110 | } 111 | } 112 | ``` 113 | 114 | _Bramble query with array boundary query_ 115 | 116 | ```graphql 117 | { 118 | _result: movies(ids: ["1", "2"]) { 119 | id 120 | title 121 | } 122 | } 123 | ``` 124 | 125 | ### How it works 126 | 127 | When dealing with boundary types, Bramble will split the query into multiple steps: 128 | 129 | 1. Execute the root query 130 | 2. Execute boundary queries on the previous result 131 | 3. Merge the results 132 | 133 | For example: 134 | 135 | _Schema_ 136 | 137 | ```graphql 138 | type Movie { 139 | id: ID! 140 | title: String! # Defined in service A 141 | compTitles: [Movie!] # Defined in service B 142 | } 143 | 144 | type Query { 145 | movieSearch(title: String!): [Movie!] 146 | } 147 | ``` 148 | 149 | _Query_ 150 | 151 | ```graphql 152 | query { 153 | movieSearch(title: "Tenet") { 154 | title 155 | compTitles { 156 | title 157 | } 158 | } 159 | } 160 | ``` 161 | 162 | _Execution_ 163 | 164 |
165 |
166 | ## Namespaces
167 |
168 | A namespace is a type that can be shared among services for the purpose of... namespacing.
169 |
170 | Namespaces types must respect the following rules:
171 |
172 | - Use the `@namespace` directive
173 | - End with `Query` or `Mutation` (e.g. `MyNamespaceQuery`)
174 | - Can only be returned by a root field or another namespace.
175 | - Have no arguments
176 |
177 | ### Example
178 |
179 | _Service A_
180 |
181 | ```graphql
182 | directive @namespace on OBJECT
183 |
184 | type Query {
185 | myNamespace: MyNamespaceQuery!
186 | }
187 |
188 | type MyNamespaceQuery @namespace {
189 | serviceA: String!
190 | }
191 | ```
192 |
193 | _Service B_
194 |
195 | ```graphql
196 | directive @namespace on OBJECT
197 |
198 | type Query {
199 | myNamespace: MyNamespaceQuery!
200 | }
201 |
202 | type MyNamespaceQuery @namespace {
203 | serviceB: String!
204 | }
205 | ```
206 |
207 | _Merged Schema_
208 |
209 | ```graphql
210 | type Query {
211 | myNamespace: MyNamespaceQuery!
212 | }
213 |
214 | type MyNamespaceQuery {
215 | serviceA: String!
216 | serviceB: String!
217 | }
218 | ```
219 |
--------------------------------------------------------------------------------
/plugins/admin_ui.html.template:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Aggregated services
154 |-
155 | {{range .Services}}
156 |
-
157 | 158 |163 | 170 |
{{.Name}}
159 |{{.Version}}160 |{{.ServiceURL}}161 |{{.Status}}162 |
171 | {{end}}
172 |
Test schema merge
174 | {{if ne .TestedSchema "" }} 175 |
176 | {{if eq .TestSchemaError ""}}
177 |
193 | {{end}}
194 |
199 |
200 |
201 |
202 |
--------------------------------------------------------------------------------
/client_test.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "net/http"
6 | "net/http/cookiejar"
7 | "net/http/httptest"
8 | "net/url"
9 | "testing"
10 |
11 | "github.com/99designs/gqlgen/graphql"
12 | "github.com/stretchr/testify/assert"
13 | "github.com/stretchr/testify/require"
14 | )
15 |
16 | func TestGraphqlClient(t *testing.T) {
17 | t.Run("basic request", func(t *testing.T) {
18 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
19 | w.Write([]byte(`{
20 | "data": {
21 | "root": {
22 | "test": "value"
23 | }
24 | }
25 | }`))
26 | }))
27 |
28 | c := NewClient()
29 | var res struct {
30 | Root struct {
31 | Test string
32 | }
33 | }
34 |
35 | err := c.Request(context.Background(), srv.URL, &Request{}, &res)
36 | assert.NoError(t, err)
37 | assert.Equal(t, "value", res.Root.Test)
38 | })
39 |
40 | t.Run("without keep-alive", func(t *testing.T) {
41 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
42 | require.Equal(t, "close", r.Header.Get("Connection"))
43 | w.Write([]byte(`{
44 | "data": {
45 | "root": {
46 | "test": "value"
47 | }
48 | }
49 | }`))
50 | }))
51 |
52 | c := NewClientWithoutKeepAlive()
53 | err := c.Request(context.Background(), srv.URL, &Request{}, nil)
54 | assert.NoError(t, err)
55 | })
56 |
57 | t.Run("with http client", func(t *testing.T) {
58 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
59 | cookie, err := r.Cookie("test_cookie")
60 | require.NoError(t, err)
61 | assert.Equal(t, "test_value", cookie.Value)
62 | }))
63 |
64 | jar, err := cookiejar.New(nil)
65 | require.NoError(t, err)
66 |
67 | serverURL, err := url.Parse(srv.URL)
68 | require.NoError(t, err)
69 |
70 | jar.SetCookies(serverURL, []*http.Cookie{
71 | {
72 |
73 | Name: "test_cookie",
74 | Value: "test_value",
75 | },
76 | })
77 |
78 | httpClient := &http.Client{Jar: jar}
79 | c := NewClient(WithHTTPClient(httpClient))
80 | var res interface{}
81 | _ = c.Request(context.Background(), srv.URL, &Request{}, &res)
82 | })
83 |
84 | t.Run("with user agent", func(t *testing.T) {
85 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
86 | assert.Equal(t, "My User Agent", r.Header.Get("User-Agent"))
87 | }))
88 |
89 | c := NewClient(WithUserAgent("My User Agent"))
90 | var res interface{}
91 | _ = c.Request(context.Background(), srv.URL, &Request{}, &res)
92 | })
93 |
94 | t.Run("with max response size", func(t *testing.T) {
95 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
96 | w.Write([]byte(`{ "data": "long response" }`))
97 | }))
98 |
99 | c := NewClient(WithMaxResponseSize(1))
100 | var res interface{}
101 | err := c.Request(context.Background(), srv.URL, &Request{}, &res)
102 | require.Error(t, err)
103 | assert.Equal(t, "response exceeded maximum size of 1 bytes", err.Error())
104 | })
105 | }
106 | func TestMultipartClient(t *testing.T) {
107 | nestedMap := map[string]any{
108 | "node1": map[string]any{
109 | "node11": map[string]any{
110 | "leaf111": graphql.Upload{},
111 | "leaf112": "someThing",
112 | "node113": map[string]any{"leaf1131": graphql.Upload{}},
113 | },
114 | "leaf12": 42,
115 | "leaf13": graphql.Upload{},
116 | },
117 | "node2": map[string]any{
118 | "leaf21": false,
119 | "node21": map[string]any{
120 | "leaf211": &graphql.Upload{},
121 | },
122 | },
123 | "node3": graphql.Upload{},
124 | "node4": []graphql.Upload{{}, {}},
125 | "node5": []*graphql.Upload{{}, {}},
126 | }
127 |
128 | t.Run("parseMultipartVariables", func(t *testing.T) {
129 | _, fileMap := prepareUploadsFromVariables(nestedMap)
130 | fileMapKeys := []string{}
131 | fileMapValues := []string{}
132 | for k, v := range fileMap {
133 | fileMapKeys = append(fileMapKeys, k)
134 | fileMapValues = append(fileMapValues, v...)
135 | }
136 | assert.ElementsMatch(t, fileMapKeys, []string{"file0", "file1", "file2", "file3", "file4", "file5", "file6", "file7", "file8"})
137 | assert.ElementsMatch(t, fileMapValues, []string{
138 | "variables.node1.node11.node113.leaf1131",
139 | "variables.node1.node11.leaf111",
140 | "variables.node1.leaf13",
141 | "variables.node2.node21.leaf211",
142 | "variables.node3",
143 | "variables.node4.0",
144 | "variables.node4.1",
145 | "variables.node5.0",
146 | "variables.node5.1",
147 | })
148 | assert.Equal(
149 | t,
150 | map[string]any{
151 | "node1": map[string]any{
152 | "node11": map[string]any{
153 | "leaf111": nil,
154 | "leaf112": "someThing",
155 | "node113": map[string]any{"leaf1131": nil},
156 | },
157 | "leaf12": 42,
158 | "leaf13": nil,
159 | },
160 | "node2": map[string]any{
161 | "leaf21": false,
162 | "node21": map[string]any{
163 | "leaf211": nil,
164 | },
165 | },
166 | "node3": nil,
167 | "node4": []*struct{}{nil, nil},
168 | "node5": []*struct{}{nil, nil},
169 | },
170 | nestedMap,
171 | )
172 | })
173 |
174 | t.Run("multipart request", func(t *testing.T) {
175 | srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
176 | w.Write([]byte(`{ "data": {"root": "multipart response"} }`))
177 | }))
178 |
179 | c := NewClient()
180 | req := &Request{Headers: make(http.Header)}
181 | req.Headers.Set("Content-Type", "multipart/form-data")
182 |
183 | var res struct {
184 | Root string
185 | }
186 | err := c.Request(
187 | context.Background(),
188 | srv.URL,
189 | req,
190 | &res,
191 | )
192 | require.NoError(t, err)
193 | assert.Equal(t, "multipart response", res.Root)
194 | })
195 | }
196 |
--------------------------------------------------------------------------------
/docs/access-control.md:
--------------------------------------------------------------------------------
1 | # Access Control
2 |
3 | Bramble has a simple (yet powerful) access control mechanism allowing plugins to define field-level permissions for incoming queries.
4 |
5 | !> Permissions must be added to incoming queries through plugins, use the provided [JWT plugin](/plugins?id=jwt-auth) or learn [how to write a plugin](write-plugin.md).
6 |
7 | ## OperationPermissions
8 |
9 | The [`OperationPermissions`](https://pkg.go.dev/github.com/movio/bramble/bramble#OperationPermissions) type defines which fields can be requested for a given query.
10 |
11 | By adding an `OperationPermissions` to the query context it is possible to control the allowed fields for that query.
12 |
13 | At every level of the schema it is possible to:
14 |
15 | - Enable a list of white-listed subfields
16 | or
17 | - Enable all subfields
18 |
19 | ### JSON Representation
20 |
21 | `OperationPermissions` implements a custom JSON unmarshaller, so it is possible to represent the permissions with a more accessible representation.
22 |
23 | ```json
24 | {
25 | "query": {
26 | "movies": "*",
27 | "cinemas": ["id", "name"]
28 | }
29 | }
30 | ```
31 |
32 | The syntax is as follow:
33 |
34 | - `"*"`: Allows all sub-fields
35 | - An array of fields `[field1, field2]`: Allows the specified fields and all their sub-fields
36 |
37 | See below for more examples.
38 |
39 | ### Examples
40 |
41 | Let's imagine we have the following schema:
42 |
43 | ```graphql
44 | type Cast {
45 | firstName: String!
46 | lastName: String!
47 | }
48 |
49 | type Movie {
50 | id: ID!
51 | title: String!
52 | releaseYear: Int!
53 | cast: [Cast!]
54 | }
55 |
56 | type Cinema {
57 | id: ID!
58 | name: String!
59 | location: String!
60 | }
61 |
62 | type Query {
63 | movies: [Movie!]
64 | cinemas: [Cinemas!]
65 | }
66 | ```
67 |
68 | #### AllowAll and sub-fields
69 |
70 | If we want to allow the user to query every field on `Movie` but only a subset for `Cinema` we could define the permissions as:
71 |
72 | ```go
73 | OperationPermissions{
74 | AllowedRootQueryFields: AllowedFields{
75 | AllowedSubFields: map[string]AllowedFields{
76 | "movies": AllowedField{
77 | AllowAll: true,
78 | }
79 | "cinemas": AllowedField{
80 | AllowedSubFields: map[string]AllowedField{
81 | "id": AllowedField{},
82 | "name": AllowedField{},
83 | }
84 | }
85 | }
86 | }
87 | }
88 | ```
89 |
90 | This can be more easily represented with JSON:
91 |
92 | ```json
93 | {
94 | "query": {
95 | "movies": "*",
96 | "cinemas": ["id", "name"]
97 | }
98 | }
99 | ```
100 |
101 | Now if we try to execute the following query:
102 |
103 | ```graphql
104 | query {
105 | cinemas {
106 | name
107 | location
108 | }
109 | }
110 | ```
111 |
112 | Bramble will filter out unauthorized fields and execute
113 |
114 | ```graphql
115 | query {
116 | cinemas {
117 | name
118 | }
119 | }
120 | ```
121 |
122 | #### Allow all
123 |
124 | ```json
125 | {
126 | "query": "*",
127 | "mutation": "*"
128 | }
129 | ```
130 |
131 | will give access to every query and mutation.
132 |
133 | #### Nested fields
134 |
135 | If we want to allow only `movies.title` and `movies.cast.firstName` we can write something like:
136 |
137 | ```json
138 | {
139 | "query": {
140 | "movies": {
141 | "title": [],
142 | "cast": {
143 | "firstName": []
144 | }
145 | }
146 | }
147 | }
148 | ```
149 |
150 | On the other hand, using the array notation
151 |
152 | ```json
153 | {
154 | "query": {
155 | "movies": ["title", "cast"]
156 | }
157 | }
158 | ```
159 |
160 | would give access to all subfields of the named fields so that
161 |
162 | ```graphql
163 | query {
164 | movies {
165 | title
166 | cast {
167 | firstName
168 | lastName
169 | }
170 | }
171 | }
172 | ```
173 |
174 | is valid.
175 |
176 | ### Testing the permissions
177 |
178 | It is possible to programmatically check what the allowed schema would be for
179 | a given set of permissions by using the `OperationPermissions.FilterSchema`
180 | method.
181 |
182 | 178 | Schema merged successfully! 179 |
180 | 187 | {{else}} 188 |189 | {{.TestSchemaError}} 190 |
191 | {{end}} 192 |
183 |
217 |
218 | ## Setting permissions for incoming requests
219 |
220 | From a plugin it is possible to add permissions to any incoming request context using `bramble.AddPermissionsToContext`.
221 |
222 | ```go
223 | func (p *MyPlugin) ApplyMiddlewarePublicMux(h http.Handler) http.Handler {
224 | return http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
225 | r = r.WithContext(bramble.AddPermissionsToContext(r.Context(), permissions))
226 | h.ServeHTTP(rw, r)
227 | }
228 | }
229 | ```
230 |
231 | If Bramble finds permissions in a query context it will automatically filter out unauthorized fields.
232 |
233 | If a query contains both authorized and unauthorized fields:
234 |
235 | - unauthorized fields will be removed from the query
236 | - an error will be added to the response
237 | - **the query will still proceed with authorized fields**
238 |
239 | ## JWT and role based access control
240 |
241 | Bramble provides a simple plugin for JWT and role based access control.
242 |
243 | The permissions syntax described above can be used to configure roles (i.e. a named set of permissions).
244 |
245 | See [JWT Auth plugin](/plugins?id=jwt-auth)
246 |
247 | !> When using roles on a public-facing instance it is recommended to use
248 | fine-grained whitelisting to avoid newly federated services to inadvertently
249 | expose new fields publicly.
250 |
--------------------------------------------------------------------------------
/gateway_test.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "encoding/json"
6 | "fmt"
7 | "io"
8 | "log/slog"
9 | "net/http"
10 | "net/http/httptest"
11 | "strings"
12 | "testing"
13 |
14 | "github.com/stretchr/testify/assert"
15 | "github.com/stretchr/testify/require"
16 | )
17 |
18 | func TestGatewayQuery(t *testing.T) {
19 | server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
20 | var req struct {
21 | Query string
22 | }
23 | json.NewDecoder(r.Body).Decode(&req)
24 |
25 | if strings.Contains(req.Query, "service") {
26 | // initial query to get schema
27 | schema := `type Service {
28 | name: String!
29 | version: String!
30 | schema: String!
31 | }
32 |
33 | type Query {
34 | test: String
35 | service: Service!
36 | }`
37 | encodedSchema, _ := json.Marshal(schema)
38 | fmt.Fprintf(w, `{
39 | "data": {
40 | "service": {
41 | "schema": %s,
42 | "version": "1.0",
43 | "name": "test-service"
44 | }
45 | }
46 | }`, string(encodedSchema))
47 | assert.Equal(t, "Bramble/dev (update)", r.Header.Get("User-Agent"))
48 | } else {
49 | w.Write([]byte(`{ "data": { "test": "Hello" }}`))
50 | assert.Equal(t, "Bramble/dev (query)", r.Header.Get("User-Agent"))
51 | }
52 | }))
53 | client := NewClient(WithUserAgent(GenerateUserAgent("query")))
54 | executableSchema := NewExecutableSchema(nil, 50, client, NewService(server.URL))
55 | err := executableSchema.UpdateSchema(context.TODO(), true)
56 | require.NoError(t, err)
57 | gtw := NewGateway(executableSchema, []Plugin{})
58 | rec := httptest.NewRecorder()
59 | req := httptest.NewRequest(http.MethodPost, "/query", strings.NewReader(`
60 | {
61 | "query": "query gatewaytest { test }"
62 | }`))
63 | req.Header.Set("Content-Type", "application/json; charset=utf-8")
64 | req.Header.Set("Accept", "application/json; charset=utf-8")
65 |
66 | gtw.Router(&Config{}).ServeHTTP(rec, req)
67 | assert.Equal(t, http.StatusOK, rec.Code)
68 | assert.JSONEq(t, `{"data": { "test": "Hello" }}`, rec.Body.String())
69 | }
70 |
71 | func TestRequestNoBodyLoggingOnInfo(t *testing.T) {
72 | server := NewGateway(NewExecutableSchema(nil, 50, nil), nil).Router(&Config{})
73 |
74 | body := map[string]interface{}{
75 | "foo": "bar",
76 | }
77 | jr, jw := io.Pipe()
78 | go func() {
79 | enc := json.NewEncoder(jw)
80 | enc.Encode(body)
81 | jw.Close()
82 | }()
83 | defer jr.Close()
84 |
85 | req := httptest.NewRequest("POST", "/query", jr)
86 | req.Header.Set("Content-Type", "application/json")
87 | w := httptest.NewRecorder()
88 | obj := collectLogEvent(t, &slog.HandlerOptions{Level: slog.LevelInfo}, func() {
89 | server.ServeHTTP(w, req)
90 | })
91 | resp := w.Result()
92 |
93 | assert.NotNil(t, obj)
94 | assert.Equal(t, float64(resp.StatusCode), obj["response.status"])
95 | assert.Empty(t, obj["request.content-type"])
96 | assert.Empty(t, obj["request.body"])
97 | }
98 |
99 | func TestRequestJSONBodyLogging(t *testing.T) {
100 | server := NewGateway(NewExecutableSchema(nil, 50, nil), nil).Router(&Config{})
101 |
102 | body := map[string]interface{}{
103 | "foo": "bar",
104 | }
105 | jr, jw := io.Pipe()
106 | go func() {
107 | enc := json.NewEncoder(jw)
108 | enc.Encode(body)
109 | jw.Close()
110 | }()
111 | defer jr.Close()
112 |
113 | req := httptest.NewRequest("POST", "/query", jr)
114 | req.Header.Set("Content-Type", "application/json")
115 | w := httptest.NewRecorder()
116 | obj := collectLogEvent(t, &slog.HandlerOptions{Level: slog.LevelDebug}, func() {
117 | server.ServeHTTP(w, req)
118 | })
119 | resp := w.Result()
120 |
121 | assert.NotNil(t, obj)
122 | assert.Equal(t, float64(resp.StatusCode), obj["response.status"])
123 | assert.Equal(t, "application/json", obj["request.content-type"])
124 | assert.IsType(t, make(map[string]interface{}), obj["request.body"])
125 | assert.Equal(t, body, obj["request.body"])
126 | }
127 |
128 | func TestRequestInvalidJSONBodyLogging(t *testing.T) {
129 | server := NewGateway(nil, nil).Router(&Config{})
130 |
131 | body := `{ "invalid": "json`
132 | jr, jw := io.Pipe()
133 | go func() {
134 | jw.Write([]byte(body))
135 | jw.Close()
136 | }()
137 | defer jr.Close()
138 |
139 | req := httptest.NewRequest("POST", "/query", jr)
140 | req.Header.Set("Content-Type", "application/json")
141 | w := httptest.NewRecorder()
142 | obj := collectLogEvent(t, &slog.HandlerOptions{Level: slog.LevelDebug}, func() {
143 | server.ServeHTTP(w, req)
144 | })
145 | w.Result()
146 |
147 | assert.NotNil(t, obj)
148 | assert.Equal(t, "application/json", obj["request.content-type"])
149 | assert.IsType(t, "string", obj["request.body"])
150 | assert.Equal(t, body, obj["request.body"])
151 | assert.Equal(t, "unexpected end of JSON input", obj["request.error"])
152 | }
153 |
154 | func TestRequestTextBodyLogging(t *testing.T) {
155 | server := NewGateway(nil, nil).Router(&Config{})
156 |
157 | body := `the request body`
158 | jr, jw := io.Pipe()
159 | go func() {
160 | jw.Write([]byte(body))
161 | jw.Close()
162 | }()
163 | defer jr.Close()
164 |
165 | req := httptest.NewRequest("POST", "/query", jr)
166 | req.Header.Set("Content-Type", "text/plain")
167 | w := httptest.NewRecorder()
168 | obj := collectLogEvent(t, &slog.HandlerOptions{Level: slog.LevelDebug}, func() {
169 | server.ServeHTTP(w, req)
170 | })
171 | w.Result()
172 |
173 | assert.NotNil(t, obj)
174 | assert.Equal(t, "text/plain", obj["request.content-type"])
175 | assert.IsType(t, "string", obj["request.body"])
176 | assert.Equal(t, body, obj["request.body"])
177 | assert.Equal(t, nil, obj["request.error"])
178 | }
179 |
180 | func TestDebugMiddleware(t *testing.T) {
181 | t.Run("without debug header", func(t *testing.T) {
182 | called := false
183 | req := httptest.NewRequest("POST", "/", nil)
184 | h := func(w http.ResponseWriter, r *http.Request) {
185 | called = true
186 | info, ok := r.Context().Value(DebugKey).(DebugInfo)
187 | assert.True(t, ok, "context should include debugInfo")
188 | assert.False(t, info.Variables)
189 | assert.False(t, info.Query)
190 | assert.False(t, info.Plan)
191 | w.WriteHeader(http.StatusOK)
192 | }
193 | server := debugMiddleware(http.HandlerFunc(h))
194 | w := httptest.NewRecorder()
195 | server.ServeHTTP(w, req)
196 | assert.True(t, called, "handler not called")
197 | })
198 | for header, expected := range map[string]DebugInfo{
199 | "all": {
200 | Variables: true,
201 | Query: true,
202 | Plan: true,
203 | },
204 | "query": {
205 | Query: true,
206 | },
207 | "variables": {
208 | Variables: true,
209 | },
210 | "plan": {
211 | Plan: true,
212 | },
213 | "query plan": {
214 | Query: true,
215 | Plan: true,
216 | },
217 | } {
218 | t.Run("with debug header value all", func(t *testing.T) {
219 | called := false
220 | req := httptest.NewRequest("POST", "/", nil)
221 | req.Header.Set(debugHeader, header)
222 | h := func(w http.ResponseWriter, r *http.Request) {
223 | called = true
224 | info, ok := r.Context().Value(DebugKey).(DebugInfo)
225 | assert.True(t, ok, "context should include debugInfo")
226 | assert.Equal(t, expected.Variables, info.Variables)
227 | assert.Equal(t, expected.Query, info.Query)
228 | assert.Equal(t, expected.Plan, info.Plan)
229 | w.WriteHeader(http.StatusOK)
230 | }
231 | server := debugMiddleware(http.HandlerFunc(h))
232 | w := httptest.NewRecorder()
233 | server.ServeHTTP(w, req)
234 | assert.True(t, called, "handler not called")
235 | })
236 | }
237 | }
238 |
--------------------------------------------------------------------------------
/telemetry.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "context"
5 | "errors"
6 | log "log/slog"
7 | "os"
8 |
9 | "go.opentelemetry.io/otel"
10 | "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
11 | "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
12 | "go.opentelemetry.io/otel/propagation"
13 | sdkmetric "go.opentelemetry.io/otel/sdk/metric"
14 | "go.opentelemetry.io/otel/sdk/resource"
15 | sdktrace "go.opentelemetry.io/otel/sdk/trace"
16 | semconv "go.opentelemetry.io/otel/semconv/v1.25.0"
17 | )
18 |
19 | // instrumentationName is used to identify the instrumentation in the
20 | // OpenTelemetry collector. It maps to the attribute `otel.library.name`.
21 | const instrumentationName string = "github.com/movio/bramble"
22 |
23 | // TelemetryConfig is the configuration for OpenTelemetry tracing and metrics.
24 | type TelemetryConfig struct {
25 | Enabled bool `json:"enabled"` // Enabled enables OpenTelemetry tracing and metrics.
26 | Insecure bool `json:"insecure"` // Insecure enables insecure communication with the OpenTelemetry collector.
27 | Endpoint string `json:"endpoint"` // Endpoint is the OpenTelemetry collector endpoint.
28 | ServiceName string `json:"service_name"` // ServiceName is the name of the service.
29 | }
30 |
31 | // InitializesTelemetry initializes OpenTelemetry tracing and metrics. It
32 | // returns a shutdown function that should be called when the application
33 | // terminates.
34 | func InitTelemetry(ctx context.Context, cfg TelemetryConfig) (func(context.Context) error, error) {
35 | endpoint := os.Getenv("BRAMBLE_OTEL_ENDPOINT")
36 | if endpoint != "" {
37 | cfg.Endpoint = endpoint
38 | }
39 |
40 | // If telemetry is disabled, return a no-op shutdown function. The standard
41 | // behaviour of the application will not be affected, since a
42 | // `NoopTracerProvider` is used by default.
43 | if !cfg.Enabled || cfg.Endpoint == "" {
44 | return func(context.Context) error { return nil }, nil
45 | }
46 |
47 | var flushAndShutdownFuncs []func(context.Context) error
48 |
49 | // flushAndShutdown calls cleanup functions registered via shutdownFuncs.
50 | // The errors from the calls are joined.
51 | // Each registered cleanup will be invoked once.
52 | flushAndShutdown := func(ctx context.Context) error {
53 | var err error
54 | for _, fn := range flushAndShutdownFuncs {
55 | err = errors.Join(err, fn(ctx))
56 | }
57 | flushAndShutdownFuncs = nil
58 | return err
59 | }
60 |
61 | // handleErr calls shutdown for cleanup and makes sure that all errors are returned.
62 | handleErr := func(inErr error) error {
63 | return errors.Join(inErr, flushAndShutdown(ctx))
64 | }
65 |
66 | if cfg.ServiceName == "" {
67 | cfg.ServiceName = "bramble"
68 | }
69 |
70 | // Set up resource.
71 | res, err := resources(cfg)
72 | if err != nil {
73 | return nil, handleErr(err)
74 | }
75 |
76 | // Set up propagator.
77 | prop := propagation.NewCompositeTextMapPropagator(
78 | propagation.TraceContext{},
79 | propagation.Baggage{},
80 | )
81 |
82 | otel.SetTextMapPropagator(prop)
83 |
84 | otel.SetErrorHandler(otel.ErrorHandlerFunc(func(err error) {
85 | log.Error(err.Error())
86 | }))
87 |
88 | traceShutdown, err := setupOTelTraceProvider(ctx, cfg, res)
89 | if err != nil {
90 | return nil, handleErr(err)
91 | }
92 |
93 | flushAndShutdownFuncs = append(flushAndShutdownFuncs, traceShutdown...)
94 |
95 | meterShutdown, err := setupOTelMeterProvider(ctx, cfg, res)
96 | if err != nil {
97 | return nil, handleErr(err)
98 | }
99 |
100 | flushAndShutdownFuncs = append(flushAndShutdownFuncs, meterShutdown...)
101 |
102 | return flushAndShutdown, nil
103 | }
104 |
105 | func setupOTelTraceProvider(ctx context.Context, cfg TelemetryConfig, res *resource.Resource) ([]func(context.Context) error, error) {
106 | // Set up exporter.
107 | traceExp, err := newTraceExporter(ctx, cfg.Endpoint, cfg.Insecure)
108 | if err != nil {
109 | return nil, err
110 | }
111 |
112 | // Set up trace provider.
113 | tracerProvider, err := newTraceProvider(traceExp, res)
114 | if err != nil {
115 | return nil, err
116 | }
117 |
118 | var shutdownFuncs []func(context.Context) error
119 | shutdownFuncs = append(shutdownFuncs,
120 | tracerProvider.ForceFlush, // ForceFlush exports any traces that have not yet been exported.
121 | tracerProvider.Shutdown, // Shutdown stops the export pipeline and returns the last error.
122 | )
123 |
124 | otel.SetTracerProvider(tracerProvider)
125 | return shutdownFuncs, nil
126 | }
127 |
128 | func newTraceExporter(ctx context.Context, endpoint string, insecure bool) (sdktrace.SpanExporter, error) {
129 | exporterOpts := []otlptracegrpc.Option{
130 | otlptracegrpc.WithEndpoint(endpoint),
131 | }
132 |
133 | if insecure {
134 | exporterOpts = append(exporterOpts, otlptracegrpc.WithInsecure())
135 | }
136 |
137 | traceExporter, err := otlptracegrpc.New(ctx, exporterOpts...)
138 | if err != nil {
139 | return nil, err
140 | }
141 |
142 | return traceExporter, nil
143 | }
144 |
145 | func newTraceProvider(exp sdktrace.SpanExporter, res *resource.Resource) (*sdktrace.TracerProvider, error) {
146 | // ParentBased sampler is used to sample traces based on the parent span.
147 | // This is useful for sampling traces based on the sampling decision of the
148 | // upstream service. We follow the default sampling strategy of the
149 | // OpenTelemetry Sampler.
150 | parentSamplers := []sdktrace.ParentBasedSamplerOption{
151 | sdktrace.WithLocalParentSampled(sdktrace.AlwaysSample()),
152 | sdktrace.WithLocalParentNotSampled(sdktrace.NeverSample()),
153 | sdktrace.WithRemoteParentSampled(sdktrace.AlwaysSample()),
154 | sdktrace.WithRemoteParentNotSampled(sdktrace.NeverSample()),
155 | }
156 |
157 | traceProvider := sdktrace.NewTracerProvider(
158 | // By default we'll trace all requests if not parent trace is found.
159 | // Otherwise we follow the rules from above.
160 | sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.AlwaysSample(), parentSamplers...)),
161 | sdktrace.WithResource(res),
162 | sdktrace.WithSpanProcessor(sdktrace.NewBatchSpanProcessor(exp)),
163 | )
164 |
165 | return traceProvider, nil
166 | }
167 |
168 | func setupOTelMeterProvider(ctx context.Context, cfg TelemetryConfig, res *resource.Resource) ([]func(context.Context) error, error) {
169 | metricExp, err := newMetricExporter(ctx, cfg.Endpoint, cfg.Insecure)
170 | if err != nil {
171 | return nil, err
172 | }
173 |
174 | meterProvider, err := newMeterProvider(metricExp, res)
175 | if err != nil {
176 | return nil, err
177 | }
178 |
179 | var shutdownFuncs []func(context.Context) error
180 | shutdownFuncs = append(shutdownFuncs,
181 | meterProvider.ForceFlush, // ForceFlush exports any metrics that have not yet been exported.
182 | meterProvider.Shutdown, // Shutdown stops the export pipeline and returns the last error.
183 | )
184 |
185 | otel.SetMeterProvider(meterProvider)
186 | return shutdownFuncs, nil
187 | }
188 |
189 | func newMetricExporter(ctx context.Context, endpoint string, insecure bool) (sdkmetric.Exporter, error) {
190 | exporterOpts := []otlpmetricgrpc.Option{
191 | otlpmetricgrpc.WithEndpoint(endpoint),
192 | }
193 |
194 | if insecure {
195 | exporterOpts = append(exporterOpts, otlpmetricgrpc.WithInsecure())
196 | }
197 |
198 | metricExporter, err := otlpmetricgrpc.New(ctx, exporterOpts...)
199 | if err != nil {
200 | return nil, err
201 | }
202 |
203 | return metricExporter, nil
204 | }
205 |
206 | func newMeterProvider(exp sdkmetric.Exporter, res *resource.Resource) (*sdkmetric.MeterProvider, error) {
207 | meterProvider := sdkmetric.NewMeterProvider(
208 | sdkmetric.WithResource(res),
209 | sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exp)),
210 | )
211 |
212 | return meterProvider, nil
213 | }
214 |
215 | func resources(cfg TelemetryConfig) (*resource.Resource, error) {
216 | return resource.Merge(resource.Default(),
217 | resource.NewWithAttributes(semconv.SchemaURL,
218 | semconv.ServiceName(cfg.ServiceName),
219 | semconv.ServiceVersion(Version),
220 | ))
221 | }
222 |
--------------------------------------------------------------------------------
/format.go:
--------------------------------------------------------------------------------
1 | package bramble
2 |
3 | import (
4 | "bytes"
5 | "context"
6 | "fmt"
7 | "regexp"
8 | "strconv"
9 | "strings"
10 |
11 | "github.com/99designs/gqlgen/graphql"
12 | "github.com/vektah/gqlparser/v2/ast"
13 | "github.com/vektah/gqlparser/v2/formatter"
14 | )
15 |
16 | func indentPrefix(sb *strings.Builder, level int, suffix ...string) (int, error) {
17 | sb.WriteString("\n")
18 |
19 | var err error
20 | total, count := 0, 0
21 | for i := 0; i <= level; i++ {
22 | count, err = sb.WriteString(" ")
23 | total += count
24 | if err != nil {
25 | return total, err
26 | }
27 | }
28 | for _, str := range suffix {
29 | count, err = sb.WriteString(str)
30 | total += count
31 | if err != nil {
32 | return total, err
33 | }
34 | }
35 | return total, nil
36 | }
37 |
38 | func formatDocument(ctx context.Context, schema *ast.Schema, operationType string, selectionSet ast.SelectionSet) (string, map[string]interface{}) {
39 | operation, vars := formatOperation(ctx, selectionSet)
40 | return strings.ToLower(operationType) + " " + operation + formatSelectionSet(ctx, schema, selectionSet), vars
41 | }
42 |
43 | func formatOperation(ctx context.Context, selection ast.SelectionSet) (string, map[string]interface{}) {
44 | sb := strings.Builder{}
45 |
46 | if !graphql.HasOperationContext(ctx) {
47 | return "", nil
48 | }
49 | operationCtx := graphql.GetOperationContext(ctx)
50 |
51 | variables := selectionSetVariables(selection)
52 | variableNames := map[string]struct{}{}
53 | for _, s := range variables {
54 | variableNames[s] = struct{}{}
55 | }
56 |
57 | var arguments []string
58 | usedVariables := map[string]interface{}{}
59 | for _, variableDefinition := range operationCtx.Operation.VariableDefinitions {
60 | if _, exists := variableNames[variableDefinition.Variable]; !exists {
61 | continue
62 | }
63 |
64 | for varName, varValue := range operationCtx.Variables {
65 | if varName == variableDefinition.Variable {
66 | usedVariables[varName] = varValue
67 | }
68 | }
69 |
70 | argument := fmt.Sprintf("$%s: %s", variableDefinition.Variable, variableDefinition.Type.String())
71 | arguments = append(arguments, argument)
72 | }
73 |
74 | sb.WriteString(operationCtx.OperationName)
75 | if len(arguments) == 0 {
76 | return sb.String(), nil
77 | }
78 |
79 | sb.WriteString("(")
80 | sb.WriteString(strings.Join(arguments, ","))
81 | sb.WriteString(")")
82 |
83 | return sb.String(), usedVariables
84 | }
85 |
86 | func selectionSetVariables(selectionSet ast.SelectionSet) []string {
87 | var vars []string
88 | for _, s := range selectionSet {
89 | switch selection := s.(type) {
90 | case *ast.Field:
91 | vars = append(vars, directiveListVariables(selection.Directives)...)
92 | vars = append(vars, argumentListVariables(selection.Arguments)...)
93 | vars = append(vars, selectionSetVariables(selection.SelectionSet)...)
94 | case *ast.InlineFragment:
95 | vars = append(vars, directiveListVariables(selection.Directives)...)
96 | vars = append(vars, selectionSetVariables(selection.SelectionSet)...)
97 | case *ast.FragmentSpread:
98 | vars = append(vars, directiveListVariables(selection.Directives)...)
99 | }
100 | }
101 |
102 | return vars
103 | }
104 |
105 | func directiveListVariables(directives ast.DirectiveList) []string {
106 | var output []string
107 | for _, d := range directives {
108 | output = append(output, argumentListVariables(d.Arguments)...)
109 | }
110 |
111 | return output
112 | }
113 |
114 | func argumentListVariables(arguments ast.ArgumentList) []string {
115 | var output []string
116 | for _, a := range arguments {
117 | output = append(output, valueVariables(a.Value)...)
118 | }
119 |
120 | return output
121 | }
122 |
123 | func valueVariables(a *ast.Value) []string {
124 | var output []string
125 | switch a.Kind {
126 | case ast.Variable:
127 | output = append(output, a.Raw)
128 | default:
129 | for _, child := range a.Children {
130 | output = append(output, valueVariables(child.Value)...)
131 | }
132 | }
133 |
134 | return output
135 | }
136 |
137 | func formatSelectionSelectionSet(sb *strings.Builder, schema *ast.Schema, vars map[string]interface{}, level int, selectionSet ast.SelectionSet) {
138 | sb.WriteString(" {")
139 | formatSelection(sb, schema, vars, level+1, selectionSet)
140 | indentPrefix(sb, level, "}")
141 | }
142 |
143 | func formatSelection(sb *strings.Builder, schema *ast.Schema, vars map[string]interface{}, level int, selectionSet ast.SelectionSet) {
144 | for _, selection := range selectionSet {
145 | indentPrefix(sb, level)
146 | switch selection := selection.(type) {
147 | case *ast.Field:
148 | if selection.Alias != selection.Name {
149 | sb.WriteString(selection.Alias)
150 | sb.WriteString(": ")
151 | sb.WriteString(selection.Name)
152 | } else {
153 | sb.WriteString(selection.Alias)
154 | }
155 | formatArgumentList(sb, schema, vars, selection.Arguments)
156 | for _, d := range selection.Directives {
157 | sb.WriteString(" @")
158 | sb.WriteString(d.Name)
159 | formatArgumentList(sb, schema, vars, d.Arguments)
160 | }
161 | if len(selection.SelectionSet) > 0 {
162 | formatSelectionSelectionSet(sb, schema, vars, level, selection.SelectionSet)
163 | }
164 | case *ast.InlineFragment:
165 | fmt.Fprintf(sb, "... on %v", selection.TypeCondition)
166 | formatSelectionSelectionSet(sb, schema, vars, level, selection.SelectionSet)
167 | case *ast.FragmentSpread:
168 | sb.WriteString("...")
169 | sb.WriteString(selection.Name)
170 | }
171 | }
172 | }
173 |
174 | func formatArgumentList(sb *strings.Builder, schema *ast.Schema, vars map[string]interface{}, args ast.ArgumentList) {
175 | if len(args) > 0 {
176 | sb.WriteString("(")
177 | for i, arg := range args {
178 | if i != 0 {
179 | sb.WriteString(", ")
180 | }
181 | fmt.Fprintf(sb, "%s: %s", arg.Name, formatArgument(schema, arg.Value, vars))
182 | }
183 | sb.WriteString(")")
184 | }
185 | }
186 |
187 | func formatSelectionSet(ctx context.Context, schema *ast.Schema, selection ast.SelectionSet) string {
188 | vars := map[string]interface{}{}
189 | if reqctx := graphql.GetOperationContext(ctx); reqctx != nil {
190 | vars = reqctx.Variables
191 | }
192 |
193 | sb := strings.Builder{}
194 |
195 | sb.WriteString("{")
196 | formatSelection(&sb, schema, vars, 0, selection)
197 | sb.WriteString("\n}")
198 |
199 | return sb.String()
200 | }
201 |
202 | var multipleSpacesRegex = regexp.MustCompile(`\s+`)
203 |
204 | func formatSelectionSetSingleLine(ctx context.Context, schema *ast.Schema, selection ast.SelectionSet) string {
205 | return multipleSpacesRegex.ReplaceAllString(formatSelectionSet(ctx, schema, selection), " ")
206 | }
207 |
208 | func formatArgument(schema *ast.Schema, v *ast.Value, vars map[string]interface{}) string {
209 | if schema == nil {
210 | // this is to allow tests to pass to due the MarshalJSON comparator not having access
211 | // to the schema
212 | return v.String()
213 | }
214 |
215 | // this is a mix between v.String() and v.Raw(vars) as we need a string value with variables replaced
216 |
217 | if v == nil {
218 | return "