go-graph/doc.go at main · paulmanoni/go-graph · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
// Package graph provides a modern, secure GraphQL handler for Go with built-in
// authentication, validation, and an intuitive builder API.
//
// Built on top of graphql-go (github.com/graphql-go/graphql), this package simplifies
// GraphQL server development with sensible defaults while maintaining full flexibility.
//
// # Features
//
//   - Zero Config Start: Default hello world schema included
//   - Fluent Builder API: Clean, type-safe schema construction
//   - Built-in Authentication: Automatic Bearer token extraction
//   - Security First: Query depth, complexity, and introspection protection
//   - Response Sanitization: Remove field suggestions from errors
//   - Framework Agnostic: Works with net/http, Gin, Chi, or any HTTP framework
//
// # Quick Start
//
// Start immediately with the default schema:
//
//	import "github.com/paulmanoni/graph"
//
//	func main() {
//	    handler := graph.NewHTTP(&graph.GraphContext{
//	        Playground: true,
//	        DEBUG:      true,
//	    })
//	    http.Handle("/graphql", handler)
//	    http.ListenAndServe(":8080", nil)
//	}
//
// # Builder Pattern
//
// Use the fluent builder API for clean schema construction:
//
//	func getUser() graph.QueryField {
//	    return graph.NewResolver[User]("user").
//	        WithArgs(graphql.FieldConfigArgument{
//	            "id": &graphql.ArgumentConfig{Type: graphql.String},
//	        }).
//	        WithResolver(func(p graphql.ResolveParams) (interface{}, error) {
//	            id, _ := graph.GetArgString(p, "id")
//	            return User{ID: id, Name: "Alice"}, nil
//	        }).BuildQuery()
//	}
//
// # Authentication
//
// Automatic Bearer token extraction with optional user details fetching:
//
//	handler := graph.NewHTTP(&graph.GraphContext{
//	    SchemaParams: &graph.SchemaBuilderParams{
//	        QueryFields: []graph.QueryField{getProtectedQuery()},
//	    },
//	    UserDetailsFn: func(ctx context.Context, token string) (context.Context, interface{}, error) {
//	        user, err := validateAndGetUser(token)
//	        if err != nil {
//	            return ctx, nil, err
//	        }
//	        // Add values to context accessible via p.Context.Value() in resolvers
//	        ctx = context.WithValue(ctx, "userID", user.ID)
//	        return ctx, user, nil
//	    },
//	})
//
// Access token in resolvers:
//
//	func getProtectedQuery() graph.QueryField {
//	    return graph.NewResolver[User]("me").
//	        WithResolver(func(p graphql.ResolveParams) (interface{}, error) {
//	            token, err := graph.GetRootString(p, "token")
//	            if err != nil {
//	                return nil, fmt.Errorf("authentication required")
//	            }
//	            // Use token...
//	        }).BuildQuery()
//	}
//
// # Security
//
// Enable security features for production:
//
//	handler := graph.NewHTTP(&graph.GraphContext{
//	    SchemaParams:       &graph.SchemaBuilderParams{...},
//	    DEBUG:              false,  // Enable security features
//	    EnableValidation:   true,   // Max depth: 10, Max aliases: 4, Max complexity: 200
//	    EnableSanitization: true,   // Remove field suggestions from errors
//	    Playground:         false,  // Disable playground in production
//	})
//
// # Helper Functions
//
// Extract arguments safely:
//
//	name, err := graph.GetArgString(p, "name")
//	age, err := graph.GetArgInt(p, "age")
//	active, err := graph.GetArgBool(p, "active")
//
// Access root values:
//
//	token, err := graph.GetRootString(p, "token")
//	var user User
//	err := graph.GetRootInfo(p, "details", &user)
//
// For more information, see https://github.com/paulmanoni/graph
package graph