gqlgen Documentation

For WebSocket-based subscriptions, authentication typically happens during the connection initialization phase. You can use transport.WebsocketInitFunc within the AddTransport method to process the connection's initial payload.

1. Define an InitFunc: Create a function matching the transport.WebsocketInitFunc signature. This function receives the transport.InitPayload (a map of values sent by the client).
2. Extract Credentials: Access the payload (e.g., initPayload["authToken"]) to verify the user.
3. Handle Failures: If authentication fails, use transport.WithWebsocketCloseCode and transport.AppendCloseReason to set a specific close code (e.g., 1008 for policy violation) and a reason before returning an error.
4. Inject into Context: If successful, return a new context containing the user data.
5. Register the Transport: Add the transport.Websocket to your server and provide the InitFunc.

func webSocketInit(ctx context.Context, initPayload transport.InitPayload) (context.Context, *transport.InitPayload, error) {
	any := initPayload["authToken"]
	token, ok := any.(string)
	if !ok || token == "" {
		// Set close code and reason before returning error
		ctx = transport.WithWebsocketCloseCode(ctx, int(coderws.StatusPolicyViolation)) // 1008
		ctx = transport.AppendCloseReason(ctx, "missing or invalid authToken")
		return ctx, nil, errors.New("authToken not found in transport payload")
	}

	// ... verify token ...
	userId := "john.doe"
	ctxNew := context.WithValue(ctx, "username", userId)
	return ctxNew, nil, nil
}

// Registering the transport
srv.AddTransport(transport.Websocket{
	KeepAlivePingInterval: 10 * time.Second,
	Implementation: transport.CoderWebsocketImplementation{
		AcceptOptions: coderws.AcceptOptions{
			InsecureSkipVerify: true,
		},
	},
	InitFunc: transport.WebsocketInitFunc(webSocketInit),
})

Before submitting changes to gqlgen, ensure the following requirements are met:

• Testing: All new or updated behaviors must be covered by tests. Run go test ./... and ensure concurrency-sensitive changes are tested with the -race flag.
• Code Generation: If output changes, you must run go generate ./... in both the root directory and the _examples/ modules, and commit all regenerated files.
• Linting: Ensure golangci-lint run returns no errors and no unexplained //nolint directives.
• State Management: Avoid introducing new global mutable state. Dependencies must be passed explicitly rather than using package-level vars, init() side effects, or singletons.
• Clean Diffs: Ensure the diff contains only the intended changes without unrelated reformatting.
• Generator Integrity: Never hand-edit generated files; fixes must be implemented in templates/generator/config.
• Breaking Changes: Any breaking changes to resolver signatures, config schemas, CLI flags, or the exported runtime API require a proposal issue and must target the next branch.
• Documentation: All exported additions must include doc comments, and non-obvious decisions must include a comment explaining the why.

gqlgen supports binding fields from embedded (anonymous) Go structs. All standard binding rules (direct matching, methods, tags, and config mapping) apply to fields within embedded structs.

This is useful for creating thin wrappers around data access types or sharing common fields across multiple models.

Example: A Truck struct embeds a Car struct. The Truck GraphQL type can resolve fields like make or model directly from the embedded Car fields.

type Car struct {
    Make string
    ShortState string
    LongState string
    Model string
    Color string
    OdometerReading int
}

type Truck struct {
    Car
    Is4x4 bool
}

type Truck {
    make: String!
    model: String!
    state: String!
    color: String!
    odometerReading: Int!
    is4x4: Bool!
}

models:
    Truck:
        model: github.com/my/app/models.Truck
    Car:
        model: github.com/my/app/models.Car

To account for fields that are more expensive (like those returning arrays based on an input argument), you can define custom complexity functions in your gqlgen.Config.

A complexity function must match the signature: func(childComplexity, argValue int) int. The childComplexity represents the complexity of the child fields, and argValue is the value of the argument used to determine the cost (e.g., a count or limit argument).

Assign these functions to the corresponding fields in c.Complexity during server setup.

// Define a function that weights complexity by the 'count' argument
countComplexity := func(childComplexity, count int) int {
	return count * childComplexity
}

// Assign to the config
c.Complexity.Query.Posts = countComplexity
c.Complexity.Post.Related = countComplexity

// Use the config to create the schema and apply the limit
c := Config{ Resolvers: &resolvers{} }
srv := handler.New(blog.NewExecutableSchema(c))
srv.Use(extension.FixedComplexityLimit(5))