feat: GQL variables and operation name (#2993)

## Relevant issue(s)

Resolves #1441
Resolves #1395 

## Description

This PR adds support for GraphQL variables and operation name.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

## How has this been tested?

Added tests

Specify the platform(s) on which this was tested:
- MacOS

Author: nasdf

cli/request.go

@@ -11,11 +11,13 @@
 package cli
 
 import (
+	"encoding/json"
 	"io"
 	"os"
 
 	"github.com/spf13/cobra"
 
+	"github.com/sourcenetwork/defradb/client"
 	"github.com/sourcenetwork/defradb/errors"
 )
 
@@ -26,6 +28,8 @@ const (
 
 func MakeRequestCommand() *cobra.Command {
 	var filePath string
+	var operationName string
+	var variablesJSON string
 	var cmd = &cobra.Command{
 		Use:   "query [-i --identity] [request]",
 		Short: "Send a DefraDB GraphQL query request",
@@ -70,8 +74,21 @@ To learn more about the DefraDB GraphQL Query Language, refer to https://docs.so
 				return errors.New("request cannot be empty")
 			}
 
+			var options []client.RequestOption
+			if variablesJSON != "" {
+				var variables map[string]any
+				err := json.Unmarshal([]byte(variablesJSON), &variables)
+				if err != nil {
+					return err
+				}
+				options = append(options, client.WithVariables(variables))
+			}
+			if operationName != "" {
+				options = append(options, client.WithOperationName(operationName))
+			}
+
 			store := mustGetContextStore(cmd)
-			result := store.ExecRequest(cmd.Context(), request)
+			result := store.ExecRequest(cmd.Context(), request, options...)
 
 			var errors []string
 			for _, err := range result.GQL.Errors {
@@ -88,7 +105,8 @@ To learn more about the DefraDB GraphQL Query Language, refer to https://docs.so
 			return nil
 		},
 	}
-
+	cmd.Flags().StringVarP(&operationName, "operation", "o", "", "Name of the operation to execute in the query")
+	cmd.Flags().StringVarP(&variablesJSON, "variables", "v", "", "JSON encoded variables to use in the query")
 	cmd.Flags().StringVarP(&filePath, "file", "f", "", "File containing the query request")
 	return cmd
 }

client/db.go

@@ -246,7 +246,32 @@ type Store interface {
 	GetAllIndexes(context.Context) (map[CollectionName][]IndexDescription, error)
 
 	// ExecRequest executes the given GQL request against the [Store].
-	ExecRequest(ctx context.Context, request string) *RequestResult
+	ExecRequest(ctx context.Context, request string, opts ...RequestOption) *RequestResult
+}
+
+// GQLOptions contains optional arguments for GQL requests.
+type GQLOptions struct {
+	// OperationName is the name of the operation to exec.
+	OperationName string
+	// Variables is a map of names to varible values.
+	Variables map[string]any
+}
+
+// RequestOption sets an optional request setting.
+type RequestOption func(*GQLOptions)
+
+// WithOperationName sets the operation name for a GQL request.
+func WithOperationName(operationName string) RequestOption {
+	return func(o *GQLOptions) {
+		o.OperationName = operationName
+	}
+}
+
+// WithVariables sets the variables for a GQL request.
+func WithVariables(variables map[string]any) RequestOption {
+	return func(o *GQLOptions) {
+		o.Variables = variables
+	}
 }
 
 // GQLResult represents the immediate results of a GQL request.

client/mocks/db.go

@@ -30,8 +30,10 @@ defradb client query [-i --identity] [request] [flags]
 ### Options
 
 ```
-  -f, --file string   File containing the query request
-  -h, --help          help for query
+  -f, --file string        File containing the query request
+  -h, --help               help for query
+  -o, --operation string   Name of the operation to execute in the query
+  -v, --variables string   JSON encoded variables to use in the query
 ```
 
 ### Options inherited from parent commands

docs/website/references/cli/defradb_client_query.md

@@ -316,8 +316,15 @@
             },
             "graphql_request": {
                 "properties": {
+                    "operationName": {
+                        "type": "string"
+                    },
                     "query": {
                         "type": "string"
+                    },
+                    "variables": {
+                        "additionalProperties": {},
+                        "type": "object"
                     }
                 },
                 "type": "object"

docs/website/references/http/openapi.json

@@ -2,6 +2,8 @@ module github.com/sourcenetwork/defradb
 
 go 1.22
 
+toolchain go1.22.0
+
 require (
 	github.com/bits-and-blooms/bitset v1.14.3
 	github.com/bxcodec/faker v2.0.1+incompatible
@@ -45,7 +47,7 @@ require (
 	github.com/sourcenetwork/badger/v4 v4.2.1-0.20231113215945-a63444ca5276
 	github.com/sourcenetwork/corelog v0.0.8
 	github.com/sourcenetwork/go-libp2p-pubsub-rpc v0.0.14
-	github.com/sourcenetwork/graphql-go v0.7.10-0.20231113214537-a9560c1898dd
+	github.com/sourcenetwork/graphql-go v0.7.10-0.20240910200541-550a51c57c7d
 	github.com/sourcenetwork/immutable v0.3.0
 	github.com/sourcenetwork/sourcehub v0.2.1-0.20240704194128-f43f5e427274
 	github.com/spf13/cobra v1.8.1

go.mod

@@ -1394,8 +1394,8 @@ github.com/sourcenetwork/corelog v0.0.8 h1:jCo0mFBpWrfhUCGzzN3uUtPGyQv3jnITdPO1s
 github.com/sourcenetwork/corelog v0.0.8/go.mod h1:cMabHgs3kARgYTQeQYSOmaGGP8XMU6sZrHd8LFrL3zA=
 github.com/sourcenetwork/go-libp2p-pubsub-rpc v0.0.14 h1:620zKV4rOn7U5j/WsPkk4SFj0z9/pVV4bBx0BpZQgro=
 github.com/sourcenetwork/go-libp2p-pubsub-rpc v0.0.14/go.mod h1:jUoQv592uUX1u7QBjAY4C+l24X9ArhPfifOqXpDHz4U=
-github.com/sourcenetwork/graphql-go v0.7.10-0.20231113214537-a9560c1898dd h1:lmpW39/8wPJ0khWRhOcj7Bj0HYKbSmQ8rXMJw1cMB8U=
-github.com/sourcenetwork/graphql-go v0.7.10-0.20231113214537-a9560c1898dd/go.mod h1:rkahXkgRH/3vZErN1Bx+qt1+w+CV5fgaJyKKWgISe4U=
+github.com/sourcenetwork/graphql-go v0.7.10-0.20240910200541-550a51c57c7d h1:gpBJx/mKmpelxZfHT4AYhPYFgSy8DKp/Ca+bBzIIy2A=
+github.com/sourcenetwork/graphql-go v0.7.10-0.20240910200541-550a51c57c7d/go.mod h1:rkahXkgRH/3vZErN1Bx+qt1+w+CV5fgaJyKKWgISe4U=
 github.com/sourcenetwork/immutable v0.3.0 h1:gHPtGvLrTBTK5YpDAhMU+u+S8v1F6iYmc3nbZLryMdc=
 github.com/sourcenetwork/immutable v0.3.0/go.mod h1:GD7ceuh/HD7z6cdIwzKK2ctzgZ1qqYFJpsFp+8qYnbI=
 github.com/sourcenetwork/raccoondb v0.2.1-0.20240606193653-1e91e9be9234 h1:8dA9bVC1A0ChJygtsUfNsek3oR0GnwpLoYpmEo4t2mk=

go.sum

@@ -340,11 +340,22 @@ func (c *Client) GetAllIndexes(ctx context.Context) (map[client.CollectionName][
 func (c *Client) ExecRequest(
 	ctx context.Context,
 	query string,
+	opts ...client.RequestOption,
 ) *client.RequestResult {
 	methodURL := c.http.baseURL.JoinPath("graphql")
 	result := &client.RequestResult{}
 
-	body, err := json.Marshal(&GraphQLRequest{query})
+	gqlOptions := &client.GQLOptions{}
+	for _, o := range opts {
+		o(gqlOptions)
+	}
+	gqlRequest := &GraphQLRequest{
+		Query:         query,
+		OperationName: gqlOptions.OperationName,
+		Variables:     gqlOptions.Variables,
+	}
+
+	body, err := json.Marshal(gqlRequest)
 	if err != nil {
 		result.GQL.Errors = []error{err}
 		return result

http/client.go

@@ -242,7 +242,9 @@ func (s *storeHandler) PrintDump(rw http.ResponseWriter, req *http.Request) {
 }
 
 type GraphQLRequest struct {
-	Query string `json:"query"`
+	Query         string         `json:"query"`
+	OperationName string         `json:"operationName"`
+	Variables     map[string]any `json:"variables"`
 }
 
 type GraphQLResponse struct {
@@ -299,7 +301,14 @@ func (s *storeHandler) ExecRequest(rw http.ResponseWriter, req *http.Request) {
 		return
 	}
 
-	result := store.ExecRequest(req.Context(), request.Query)
+	var options []client.RequestOption
+	if request.OperationName != "" {
+		options = append(options, client.WithOperationName(request.OperationName))
+	}
+	if len(request.Variables) > 0 {
+		options = append(options, client.WithVariables(request.Variables))
+	}
+	result := store.ExecRequest(req.Context(), request.Query, options...)
 
 	if result.Subscription == nil {
 		responseJSON(rw, http.StatusOK, GraphQLResponse{result.GQL.Data, result.GQL.Errors})

http/handler_store.go

@@ -45,7 +45,7 @@ type Parser interface {
 	ExecuteIntrospection(request string) *client.RequestResult
 
 	// Parses the given request, returning a strongly typed model of that request.
-	Parse(*ast.Document) (*request.Request, []error)
+	Parse(*ast.Document, *client.GQLOptions) (*request.Request, []error)
 
 	// NewFilterFromString creates a new filter from a string.
 	NewFilterFromString(collectionType string, body string) (immutable.Option[request.Filter], error)