grpc_graphql_gateway 1.2.4

A Rust implementation of gRPC-GraphQL gateway - generates GraphQL execution code from gRPC services
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Field-Level Control

Use the `graphql.field` option to customize how individual fields are exposed in the GraphQL schema.

## Basic Field Options

```protobuf
message User {
  string id = 1 [(graphql.field) = { required: true }];
  string email = 2 [(graphql.field) = { name: "emailAddress" }];
  string internal_id = 3 [(graphql.field) = { omit: true }];
  string password_hash = 4 [(graphql.field) = { omit: true }];
}
```

## Available Options

| Option | Type | Description |
|--------|------|-------------|
| `name` | string | Override the GraphQL field name |
| `omit` | bool | Exclude this field from GraphQL schema |
| `required` | bool | Mark field as non-nullable (`!`) |
| `shareable` | bool | Federation: field can be resolved by multiple subgraphs |
| `external` | bool | Federation: field is defined in another subgraph |
| `requires` | string | Federation: fields needed from other subgraphs |
| `provides` | string | Federation: fields this resolver provides |

## Renaming Fields

Use `name` to map protobuf field names to GraphQL conventions:

```protobuf
message User {
  string user_name = 1 [(graphql.field) = { name: "username" }];
  string email_address = 2 [(graphql.field) = { name: "email" }];
  int64 created_at_unix = 3 [(graphql.field) = { name: "createdAt" }];
}
```

**Generated GraphQL:**
```graphql
type User {
  username: String!
  email: String!
  createdAt: Int!
}
```

## Omitting Fields

Hide sensitive or internal fields:

```protobuf
message User {
  string id = 1;
  string name = 2;
  string password_hash = 3 [(graphql.field) = { omit: true }];
  string internal_notes = 4 [(graphql.field) = { omit: true }];
}
```

**Generated GraphQL:**
```graphql
type User {
  id: String!
  name: String!
  # password_hash and internal_notes are not exposed
}
```

## Required Fields

Mark fields as non-nullable in GraphQL:

```protobuf
message CreateUserInput {
  string name = 1 [(graphql.field) = { required: true }];
  string email = 2 [(graphql.field) = { required: true }];
  string bio = 3;  // Optional
}
```

**Generated GraphQL:**
```graphql
input CreateUserInput {
  name: String!
  email: String!
  bio: String
}
```

## Federation Directives

For Apollo Federation, use field-level directives:

```protobuf
message User {
  string id = 1 [(graphql.field) = { 
    required: true
    shareable: true 
  }];
  
  string email = 2 [(graphql.field) = { 
    external: true 
  }];
  
  repeated Review reviews = 3 [(graphql.field) = { 
    requires: "id" 
  }];
}
```

See [Federation Directives](../federation/directives.md) for more details.

## Combining Options

Options can be combined:

```protobuf
message Product {
  string upc = 1 [(graphql.field) = { 
    required: true
    name: "id"
    shareable: true 
  }];
}
```

## Default Values

Protobuf fields have default values (empty string, 0, false). In GraphQL:

- Fields with defaults may still be nullable
- Use `required: true` to make them non-nullable
- The gateway handles type conversion automatically