composition

README

Composition

This packages implements federation composition for GraphQL and static router configuration generation.

Composition

Use Federate to produce a federated subgraph from a set of subgraphs:

package main

import (
	"fmt"
	"log"

	"github.com/wundergraph/cosmo/composition-go"
)

func main() {
	federated, err := composition.Federate(&composition.Subgraph{
		Name: "A",
		Schema: `type Query {
			query: Nested @shareable
		  }

		  type Nested @shareable {
			nest: Nested2
		  }

		  type Nested2 @shareable {
			nest: Nested3
		  }

		  type Nested3 @shareable {
			nest: Nested4
		  }

		  type Nested4 {
			name: String
		  }`,
	}, &composition.Subgraph{
		Name: "B",
		Schema: `type Query {
			query: Nested @shareable
		  }

		  type Nested @shareable {
			nest: Nested2
		  }

		  type Nested2 @shareable {
			nest: Nested3
		  }

		  type Nested3 @shareable {
			nest: Nested4
		  }

		  type Nested4 {
			age: Int
		  }`,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(federated.SDL)
}

Router configuration generation

Use BuildRouterConfiguration to produce generate a static data source configuration for the router:

package main

import (
	"fmt"
	"log"

	"github.com/wundergraph/cosmo/composition-go"
)

func main() {
	config, err := composition.BuildRouterConfiguration(&composition.Subgraph{
		Name: "A",
		Schema: `type Query {
			query: Nested @shareable
		  }

		  type Nested @shareable {
			nest: Nested2
		  }

		  type Nested2 @shareable {
			nest: Nested3
		  }

		  type Nested3 @shareable {
			nest: Nested4
		  }

		  type Nested4 {
			name: String
		  }`,
	}, &composition.Subgraph{
		Name: "B",
		Schema: `type Query {
			query: Nested @shareable
		  }

		  type Nested @shareable {
			nest: Nested2
		  }

		  type Nested2 @shareable {
			nest: Nested3
		  }

		  type Nested3 @shareable {
			nest: Nested4
		  }

		  type Nested4 {
			age: Int
		  }`,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(config)
}

Contributing

The composition-go library uses code from composition and shared, which is bundled into index.global.js. To keep this code up to date, run go generate within this package.

Performance considerations

By default, this package uses the goja runtime to run the composition algorithm. This has no dependencies and supports all platforms, but depending on your inputs it can be too slow.

For better performance, a V8 backend is also available using the wg_composition_v8 build tag, which is ~50x times faster. This uses the V8 JS engine to run the algorithm, but it increases the binary size and doesn't work on Windows, so it's not enabled by default. To enable it, use go build -tags wg_composition_v8 when compiling.

Documentation

Overview

Package composition implements federation composition for GraphQL.

Index

• func BuildRouterConfiguration(subgraphs ...*Subgraph) (string, error)
• type FederatedGraph
  • func Federate(subgraphs ...*Subgraph) (*FederatedGraph, error)
• type FieldConfiguration
• type Subgraph

Functions

func BuildRouterConfiguration

func BuildRouterConfiguration(subgraphs ...*Subgraph) (string, error)

BuildRouterConfiguration produces a federated router configuration as a string that can be saved to a file and used to configure the router data sources.

Types

type FederatedGraph

type FederatedGraph struct {
	FieldConfigurations []*FieldConfiguration `goja:"fieldConfigurations"`
	SDL                 string                `goja:"sdl"`
}

func Federate

func Federate(subgraphs ...*Subgraph) (*FederatedGraph, error)

Federate produces a federated graphs from the schemas and names of each of the subgraphs.

type FieldConfiguration

type FieldConfiguration struct {
	ArgumentNames          []string   `goja:"argumentNames"`
	FieldName              string     `goja:"fieldName"`
	TypeName               string     `goja:"typeName"`
	RequiresAuthentication bool       `goja:"requiresAuthentication"`
	RequiredScopes         [][]string `goja:"requiredScopes"`
}

type Subgraph

type Subgraph struct {
	// Name is the name of the subgraph
	Name string `goja:"name"`
	// URL is the URL of the subgraph used for sending operations
	URL string `goja:"url"`
	// Schema is the SDL of the subgraph as a string. If empty, the schema
	// is retrieved from the URL using the _service query.
	Schema               string `goja:"schema"`
	SubscriptionURL      string `goja:"subscription_url"`
	SubscriptionProtocol string `goja:"subscription_protocol"`
}

Subgraph represents a graph to be federated. URL is optional.