@xdcobra/react-native-grpc 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +176 -6
  2. package/android/src/main/java/com/reactnativegrpc/GrpcModule.java +233 -88
  3. package/ios/Grpc.h +1 -1
  4. package/ios/Grpc.m +210 -24
  5. package/lib/commonjs/channel.js +84 -0
  6. package/lib/commonjs/channel.js.map +1 -0
  7. package/lib/commonjs/client.js +531 -128
  8. package/lib/commonjs/client.js.map +1 -1
  9. package/lib/commonjs/create-client.js +206 -0
  10. package/lib/commonjs/create-client.js.map +1 -0
  11. package/lib/commonjs/index.js +32 -1
  12. package/lib/commonjs/index.js.map +1 -1
  13. package/lib/commonjs/interceptors.js +116 -0
  14. package/lib/commonjs/interceptors.js.map +1 -0
  15. package/lib/commonjs/native.js +24 -0
  16. package/lib/commonjs/native.js.map +1 -0
  17. package/lib/commonjs/retry.js +153 -0
  18. package/lib/commonjs/retry.js.map +1 -0
  19. package/lib/commonjs/status.js +54 -0
  20. package/lib/commonjs/status.js.map +1 -0
  21. package/lib/commonjs/types.js +29 -0
  22. package/lib/commonjs/types.js.map +1 -1
  23. package/lib/module/channel.js +76 -0
  24. package/lib/module/channel.js.map +1 -0
  25. package/lib/module/client.js +518 -122
  26. package/lib/module/client.js.map +1 -1
  27. package/lib/module/create-client.js +201 -0
  28. package/lib/module/create-client.js.map +1 -0
  29. package/lib/module/index.js +3 -0
  30. package/lib/module/index.js.map +1 -1
  31. package/lib/module/interceptors.js +104 -0
  32. package/lib/module/interceptors.js.map +1 -0
  33. package/lib/module/native.js +17 -0
  34. package/lib/module/native.js.map +1 -0
  35. package/lib/module/retry.js +141 -0
  36. package/lib/module/retry.js.map +1 -0
  37. package/lib/module/status.js +46 -0
  38. package/lib/module/status.js.map +1 -0
  39. package/lib/module/types.js +17 -0
  40. package/lib/module/types.js.map +1 -1
  41. package/lib/typescript/channel.d.ts +27 -0
  42. package/lib/typescript/channel.d.ts.map +1 -0
  43. package/lib/typescript/client.d.ts +56 -49
  44. package/lib/typescript/client.d.ts.map +1 -1
  45. package/lib/typescript/create-client.d.ts +65 -0
  46. package/lib/typescript/create-client.d.ts.map +1 -0
  47. package/lib/typescript/index.d.ts +5 -0
  48. package/lib/typescript/index.d.ts.map +1 -1
  49. package/lib/typescript/interceptors.d.ts +43 -0
  50. package/lib/typescript/interceptors.d.ts.map +1 -0
  51. package/lib/typescript/native.d.ts +53 -0
  52. package/lib/typescript/native.d.ts.map +1 -0
  53. package/lib/typescript/retry.d.ts +56 -0
  54. package/lib/typescript/retry.d.ts.map +1 -0
  55. package/lib/typescript/status.d.ts +24 -0
  56. package/lib/typescript/status.d.ts.map +1 -0
  57. package/lib/typescript/types.d.ts +60 -0
  58. package/lib/typescript/types.d.ts.map +1 -1
  59. package/package.json +48 -7
  60. package/src/channel.ts +110 -0
  61. package/src/client.ts +725 -200
  62. package/src/create-client.ts +391 -0
  63. package/src/index.ts +17 -0
  64. package/src/interceptors.ts +167 -0
  65. package/src/native.ts +99 -0
  66. package/src/retry.ts +208 -0
  67. package/src/status.ts +50 -0
  68. package/src/types.ts +64 -0
package/README.md CHANGED
@@ -12,11 +12,17 @@ Fork of [`@krishnafkh/react-native-grpc`](https://github.com/krishnafkh/react-na
12
12
  - Client streaming via `GrpcClient.clientStreamCall`
13
13
  - Bidirectional streaming via `GrpcClient.bidiStreamCall`
14
14
  - TLS options via `GrpcClient.setTlsOptions` (custom CA, mTLS, hostname override, SPKI pins)
15
+ - Multiple concurrent channels via `createChannel` / `GrpcChannel` (immutable per-channel config)
16
+ - Interceptors via `createChannel({ interceptors })` / `GrpcClient.setInterceptors` (auth, logging, remapping)
17
+ - Unary retry / hedging via `createChannel({ retry | hedging })` / `GrpcClient.setRetryPolicy` / `setHedgingPolicy` ([gRFC A6](https://github.com/grpc/proposal/blob/master/A6-client-retries.md)-style)
18
+ - Typed clients via Protobuf-ES `createClient` (Buf + `protoc-gen-es`)
15
19
 
16
20
  ## Installation
17
21
 
18
22
  ```sh
19
23
  npm install @xdcobra/react-native-grpc
24
+ # Typed clients (optional peer):
25
+ npm install @bufbuild/protobuf
20
26
  # or
21
27
  npm install git+https://github.com/XDcobra/react-native-grpc.git
22
28
  ```
@@ -72,7 +78,173 @@ await bidi.requests.complete(); // half-close outbound
72
78
  const done = await bidi; // resolves on trailers
73
79
  ```
74
80
 
75
- Unary, server streaming, client streaming, and bidirectional streaming. Protobuf encode/decode is BYO (e.g. `@bufbuild/protobuf`).
81
+ ### Typed clients (Buf + createClient)
82
+
83
+ Generate messages **and** `GenService` schemas with Buf + `@bufbuild/protoc-gen-es` (no custom plugin). Then call `createClient(service, GrpcClient | channel)`.
84
+
85
+ ```yaml
86
+ # buf.gen.yaml
87
+ version: v2
88
+ plugins:
89
+ - local: protoc-gen-es
90
+ out: src/gen
91
+ opt: target=ts
92
+ ```
93
+
94
+ ```sh
95
+ npm i @bufbuild/protobuf
96
+ npm i -D @bufbuild/buf @bufbuild/protoc-gen-es
97
+ npx buf generate
98
+ ```
99
+
100
+ ```ts
101
+ import { create } from '@bufbuild/protobuf';
102
+ import { createClient, GrpcClient } from '@xdcobra/react-native-grpc';
103
+ import { ExampleRequestSchema, Examples } from './gen/example_pb';
104
+
105
+ GrpcClient.setHost('api.example.com:443');
106
+ GrpcClient.initGrpcChannel();
107
+
108
+ const client = createClient(Examples, GrpcClient);
109
+ // or: createClient(Examples, createChannel({ host: '...' }))
110
+
111
+ const res = await client.sendExampleMessage(
112
+ create(ExampleRequestSchema, { message: 'Ada' }),
113
+ { authorization: 'Bearer …' },
114
+ { deadlineSeconds: 30 }
115
+ );
116
+ ```
117
+
118
+ | `methodKind` | Client shape |
119
+ |---|---|
120
+ | `unary` | `Promise<O>` |
121
+ | `server_streaming` | async iterable + `.responses` / `.cancel()` |
122
+ | `client_streaming` | `{ send(I), complete(), response: Promise<O> }` |
123
+ | `bidi_streaming` | `{ send(I), complete(), responses }` (+ async iterable) |
124
+
125
+ Path form: `/${service.typeName}/${MethodName}` (protobuf RPC name). Raw `unaryCall` / stream APIs remain for BYO bytes.
126
+
127
+ Subpath import (optional): `import { createClient } from '@xdcobra/react-native-grpc/create-client'`.
128
+
129
+ ### Multiple channels / hosts
130
+
131
+ Prefer `createChannel` when talking to more than one host (or when you want immutable per-channel TLS/deadline config). The singleton `GrpcClient` path above remains supported for single-host apps.
132
+
133
+ `createChannel` exposes the same RPC methods as `GrpcClient` (`unaryCall`, `serverStreamCall`, `clientStreamCall`, `bidiStreamCall`). Channel options (`host`, `insecure`, `tls`, deadline, keepalive, compression, response size) are set **once** in the config — there are no `setHost` / `setTlsOptions` mutators on the returned channel; reconfigure by creating a new channel.
134
+
135
+ ```ts
136
+ import { createChannel } from '@xdcobra/react-native-grpc';
137
+
138
+ const primary = createChannel({
139
+ host: 'api.example.com:443',
140
+ insecure: false,
141
+ callDeadlineSeconds: 120,
142
+ tls: {
143
+ rootCertsPem: caPem, // optional (required on iOS when using spkiSha256Pins)
144
+ certificateChainPem: clientCertPem, // mTLS (with privateKeyPem)
145
+ privateKeyPem: clientKeyPem,
146
+ hostNameOverride: 'api.example.com', // optional
147
+ spkiSha256Pins: ['sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='],
148
+ },
149
+ // optional:
150
+ // responseSizeLimit: 4 * 1024 * 1024,
151
+ // compression: { enable: true, compressorName: 'gzip' },
152
+ // keepAlive: { enable: true, keepAliveTime: 30, keepAliveTimeOut: 10 },
153
+ });
154
+
155
+ const staging = createChannel({
156
+ host: '10.0.2.2:50051',
157
+ insecure: true, // plaintext; `tls` is ignored
158
+ });
159
+
160
+ await primary.unaryCall('/package.Service/Method', requestBytes);
161
+ await staging.unaryCall('/package.Service/Method', requestBytes);
162
+
163
+ primary.close();
164
+ staging.close();
165
+ ```
166
+
167
+ `tls` uses the same `GrpcTlsOptions` fields as `GrpcClient.setTlsOptions` (see TLS matrix below). `close()` does not affect the singleton default channel.
168
+
169
+ ### Interceptors
170
+
171
+ `createChannel` accepts the same interceptor hooks as `GrpcClient.setInterceptors` (replace semantics on the singleton). Outbound hooks run index 0→n; inbound hooks run n→0 (onion). Throw from `onStart` to abort before the native call. Per-RPC extras: `options.interceptors` (appended after channel interceptors).
172
+
173
+ ```ts
174
+ import { createChannel, GrpcClient, GrpcInterceptor } from '@xdcobra/react-native-grpc';
175
+
176
+ const auth: GrpcInterceptor = {
177
+ onStart(start) {
178
+ return {
179
+ ...start,
180
+ headers: {
181
+ ...start.headers,
182
+ authorization: 'Bearer <token>',
183
+ },
184
+ };
185
+ },
186
+ };
187
+
188
+ // Multi-host / preferred
189
+ const channel = createChannel({
190
+ host: 'api.example.com:443',
191
+ interceptors: [auth],
192
+ });
193
+
194
+ // Singleton
195
+ GrpcClient.setInterceptors([auth]);
196
+
197
+ await channel.unaryCall('/package.Service/Method', requestBytes, {}, {
198
+ interceptors: [
199
+ {
200
+ onError(error) {
201
+ // remap or log
202
+ return error;
203
+ },
204
+ },
205
+ ],
206
+ });
207
+ ```
208
+
209
+ Hooks: `onStart`, `onSendMessage`, `onHeaders`, `onMessage`, `onTrailers`, `onError`.
210
+
211
+ ### Retry / hedging (unary only)
212
+
213
+ [gRFC A6](https://github.com/grpc/proposal/blob/master/A6-client-retries.md)-inspired client policies for **unary** RPCs. Retry and hedging are mutually exclusive. Streams ignore these policies. Without a policy there is no automatic retry.
214
+
215
+ ```ts
216
+ import {
217
+ createChannel,
218
+ GrpcClient,
219
+ GrpcStatusCode,
220
+ } from '@xdcobra/react-native-grpc';
221
+
222
+ const retry = {
223
+ maxAttempts: 4, // clamped to max 5
224
+ initialBackoff: '0.1s',
225
+ maxBackoff: '1s',
226
+ backoffMultiplier: 2,
227
+ retryableStatusCodes: ['UNAVAILABLE', GrpcStatusCode.RESOURCE_EXHAUSTED],
228
+ };
229
+
230
+ // Preferred multi-host path
231
+ const channel = createChannel({
232
+ host: 'api.example.com:443',
233
+ retry,
234
+ });
235
+
236
+ // Singleton
237
+ GrpcClient.setRetryPolicy(retry);
238
+ // GrpcClient.setHedgingPolicy({ maxAttempts: 3, hedgingDelay: '0.5s', nonFatalStatusCodes: ['UNAVAILABLE'] });
239
+
240
+ await channel.unaryCall('/package.Service/Method', requestBytes, {}, {
241
+ retry: false, // disable for this call
242
+ });
243
+ ```
244
+
245
+ Hedging sends parallel attempts (first success wins; siblings are cancelled). Call deadline applies across the whole retry/hedge chain.
246
+
247
+ Unary, server streaming, client streaming, and bidirectional streaming. Protobuf encode/decode is BYO (e.g. `@bufbuild/protobuf`) or via `createClient`.
76
248
 
77
249
  ### TLS matrix
78
250
 
@@ -85,7 +257,7 @@ Unary, server streaming, client streaming, and bidirectional streaming. Protobuf
85
257
  | Dial IP, cert for DNS name | `hostNameOverride` |
86
258
  | SPKI pin (SHA-256) | `spkiSha256Pins: ['base64…']` (optional `sha256/` prefix) |
87
259
 
88
- PEM values are strings (load from app assets/bundle yourself). Call `setTlsOptions` before `initGrpcChannel()`.
260
+ PEM values are strings (load from app assets/bundle yourself). On the singleton path, call `setTlsOptions` before `initGrpcChannel()`. With `createChannel`, pass the same fields under `tls` in the config.
89
261
 
90
262
  **SPKI pins:** at least one cert in the server chain must match. On **Android**, pins work with the system trust store and/or `rootCertsPem`. On **iOS** (gRPC ObjC has no handshake SPKI hook), set `rootCertsPem` to the pinned leaf/intermediate PEM as well. Pins are checked against that PEM at config time, then used as trust roots.
91
263
 
@@ -102,11 +274,9 @@ openssl x509 -in leaf.pem -pubkey -noout \
102
274
 
103
275
  Gaps vs a full gRPC client (not yet supported or not exposed):
104
276
 
105
- - **Multiple channels / hosts**: single global host; no concurrent channels
106
- - **Interceptors**: no request/response middleware
107
- - **Retry / hedging**: no client-side retry policy
277
+ - **Retry / hedging — remaining**: DNS/service-config JSON; retry throttling ([gRFC A6](https://github.com/grpc/proposal/blob/master/A6-client-retries.md)); stream retry / transparent retry after first response message; native `enableRetry` / C-core service config (JS unary policies are implemented)
108
278
  - **Cross-platform connection events**: Android-only (`onConnectionStateChange`, `enterIdle`, …)
109
- - **Codegen / stubs**: raw method paths + bytes; no generated service clients
279
+ - **Codegen — advanced**: no custom `protoc` plugin; Buf + `createClient` covers the typed path (raw bytes remain available)
110
280
 
111
281
 
112
282
  ## License