@burojs/hasura 0.4.0 → 0.5.0

package/README.md

@@ -56,22 +56,21 @@ registry rather than by branching on resource names:
 | `dataBody` | route a heavy array payload into/out of a 1:1 sibling table |
 | `live` | opt this resource into subscription-driven invalidation |
 
-#### `recoverAuth` fires on HTTP 401 — which is not how Hasura rejects a credential
-
-`config.recoverAuth` is consulted when a request comes back with HTTP **401**,
-and only then. The one capture in this repository of a real Hasura rejection —
-`packages/mock-kit/fixtures/hasura/error-unauthorized.json`, taken from a live
-backend with a deliberately malformed bearer token — came back **HTTP 200 with
-an `invalid-jwt` errors envelope**. Replayed through this provider that
-surfaces as `{ kind: 'protocol', code: 'graphql-error' }`, `recoverAuth` is
-never called, and app logic keyed on `kind: 'auth'` never fires either.
-
-So `recoverAuth` is useful for a deployment that really answers 401 (a proxy or
-gateway in front of Hasura); against Hasura's own rejection shape it is inert.
-The behaviour is pinned by `tests/fixture-fidelity.test.ts`'s
-`error-unauthorized` case, and the package's existing 401-recovery tests use a
-fabricated 401 — they are not evidence about Hasura. Keying recovery on the
-error envelope is a product decision this package has not taken.
+#### Errors Hasura sends with HTTP 200
+
+Hasura answers every GraphQL-level failure with HTTP 200, so the provider
+classifies the envelope by `extensions.code`: `access-denied` and
+`permission-error` reject as `{ kind: 'forbidden', code }`, `invalid-jwt` as
+`{ kind: 'auth', code: 'invalid-jwt' }`, and every other code as
+`{ kind: 'protocol', code: 'graphql-error' }`. When the app passes an
+`authProvider` to `<BuroProvider>`, an `auth` rejection reaches its `onError`,
+which decides whether to refresh; on `refreshed` the runtime replays a read once
+(a mutation once when it is replay-safe). `config.recoverAuth` remains the hook
+for an HTTP **401**, which a proxy or gateway in front of Hasura answers; it is
+not consulted for the envelope. A mutation whose request was sent and got no
+answer at all rejects as `{ kind: 'sent', code: 'hasura-request-sent',
+retryable: false }`: it may have been applied. Pinned by
+`tests/fixture-fidelity.test.ts` and `tests/error-kinds.test.ts`.
 
 Optimistic concurrency is available per call: pass
 `providerOptions.ifUpdatedAt` on an update and the mutation switches to a

package/dist/index.cjs

@@ -343,6 +343,63 @@ function flattenJsonbSpill(item, spill) {
 	return out;
 }
 const NOT_AUTHENTICATED_CODE = "not-authenticated";
+const FORBIDDEN_CODES = new Set(["access-denied", "permission-error"]);
+const HASURA_EXTERNAL_FAILURE_CODES = new Set([
+	"unexpected",
+	"remote-schema-error",
+	"parse-failed"
+]);
+const MUTATION_REFUSAL_CODES = new Map([["constraint-violation", "conflict"], ["validation-failed", "validation"]]);
+function graphqlError(errors, operation, external) {
+	const message = errors.map((e) => e.message).join("; ");
+	const codes = errors.flatMap((e) => typeof e.extensions?.code === "string" ? [e.extensions.code] : []);
+	if (codes.includes("invalid-jwt")) return {
+		kind: "auth",
+		code: "invalid-jwt",
+		message,
+		details: errors
+	};
+	const outside = operation === "mutation" && external ? codes.find((code) => HASURA_EXTERNAL_FAILURE_CODES.has(code) || MUTATION_REFUSAL_CODES.has(code) || FORBIDDEN_CODES.has(code)) : void 0;
+	if (outside !== void 0) return {
+		kind: "sent",
+		code: outside,
+		message,
+		retryable: false,
+		details: errors
+	};
+	const forbidden = codes.find((code) => FORBIDDEN_CODES.has(code));
+	if (forbidden !== void 0) return {
+		kind: "forbidden",
+		code: forbidden,
+		message,
+		details: errors
+	};
+	if (operation === "mutation") for (const code of codes) {
+		const kind = MUTATION_REFUSAL_CODES.get(code);
+		if (kind !== void 0) return {
+			kind,
+			code,
+			message,
+			details: errors
+		};
+	}
+	return {
+		kind: "protocol",
+		code: "graphql-error",
+		message,
+		details: errors
+	};
+}
+function answerLost(code, message, status, cause) {
+	return {
+		kind: "sent",
+		code,
+		message,
+		status,
+		retryable: false,
+		...cause === void 0 ? {} : { cause }
+	};
+}
 const LOCALE_REQUIRED_CODE = "locale-required";
 function localeWhere(m, locale) {
 	if (m.localeField === void 0) return void 0;
@@ -499,8 +556,12 @@ function createHasuraDataProvider(config) {
 	const operations = snapshotOperationRegistry(config.operations);
 	const hasCustomQueries = hasRegisteredOperationKind(operations, "query");
 	const hasCustomMutations = hasRegisteredOperationKind(operations, "mutation");
-	async function gql(query, variables, role, signal) {
+	async function gql(query, variables, role, signal, operation, external = false) {
 		try {
+			const requestBody = JSON.stringify({
+				query,
+				variables
+			});
 			const request = async (token) => {
 				const headers = {
 					"Content-Type": "application/json",
@@ -508,15 +569,24 @@ function createHasuraDataProvider(config) {
 				};
 				const effectiveRole = role === void 0 ? defaultRole : normalizeRole(role);
 				if (effectiveRole !== null) headers["X-Hasura-Role"] = effectiveRole;
-				return (config.fetchImpl ?? fetch)(endpoint, {
-					method: "POST",
-					headers,
-					body: JSON.stringify({
-						query,
-						variables
-					}),
-					signal
-				});
+				const fetchImpl = config.fetchImpl ?? fetch;
+				try {
+					return await fetchImpl(endpoint, {
+						method: "POST",
+						headers,
+						body: requestBody,
+						signal
+					});
+				} catch (cause) {
+					if (operation === "mutation" && !signal.aborted) throw {
+						kind: "sent",
+						code: "hasura-request-sent",
+						message: "Hasura did not answer a mutation; it may have been applied.",
+						retryable: false,
+						cause
+					};
+					throw cause;
+				}
 			};
 			let token = await config.getToken();
 			if (!token) throw {
@@ -534,24 +604,32 @@ function createHasuraDataProvider(config) {
 				};
 				res = await request(token);
 			}
-			if (!res.ok) throw {
-				kind: "transport",
-				code: "graphql-http-error",
-				message: `GraphQL HTTP ${res.status}`,
-				status: res.status
-			};
-			const body = await res.json();
-			if (body.errors?.length) throw {
-				kind: "protocol",
-				code: "graphql-error",
-				message: body.errors.map((e) => e.message).join("; "),
-				details: body.errors
-			};
-			if (body.data === void 0) throw {
-				kind: "protocol",
-				code: "empty-graphql-response",
-				message: "Empty GraphQL response."
-			};
+			if (!res.ok) {
+				if (operation === "mutation" && res.status >= 500) throw answerLost("hasura-answer-lost", `GraphQL HTTP ${res.status} after a mutation was sent; it may have been applied.`, res.status);
+				throw {
+					kind: "transport",
+					code: "graphql-http-error",
+					message: `GraphQL HTTP ${res.status}`,
+					status: res.status
+				};
+			}
+			let body;
+			try {
+				body = await res.json();
+				if (body === null || typeof body !== "object") throw new TypeError("The GraphQL answer is not an object.");
+			} catch (cause) {
+				if (operation === "mutation" && !signal.aborted) throw answerLost("hasura-answer-unreadable", "Hasura answered a mutation with a body that could not be read; it may have been applied.", res.status, cause);
+				throw cause;
+			}
+			if (body.errors?.length) throw graphqlError(body.errors, operation, external);
+			if (body.data === void 0) {
+				if (operation === "mutation") throw answerLost("hasura-answer-unreadable", "Hasura answered a mutation without data or errors; it may have been applied.", res.status);
+				throw {
+					kind: "protocol",
+					code: "empty-graphql-response",
+					message: "Empty GraphQL response."
+				};
+			}
 			return body.data;
 		} catch (error) {
 			throw hasuraError(error, signal, "Hasura request failed.");
@@ -577,8 +655,8 @@ function createHasuraDataProvider(config) {
 	}
 	async function executeCustomOperation(resource, operationName, input, kind, signal) {
 		const operation = registeredOperation(resource, operationName, kind);
-		const result = await gql(operation.document, operation.variables(input), operation.role ?? config.resources[resource]?.role, signal);
-		return operation.mapResult?.(result) ?? result;
+		const result = await gql(operation.document, operation.variables(input), operation.role ?? config.resources[resource]?.role, signal, kind, kind === "mutation");
+		return operation.mapResult === void 0 ? result : operation.mapResult(result);
 	}
 	function composeListWhere(m, descriptor, context) {
 		const userWhere = filtersToWhere(coerceInt64Filter(descriptor.filter, m.int64Fields));
@@ -597,7 +675,7 @@ function createHasuraDataProvider(config) {
     }`;
 		const aggVars = {};
 		if (where) aggVars.where = where;
-		return (await gql(metaQuery, where ? aggVars : void 0, m.role, signal)).meta.aggregate.count;
+		return (await gql(metaQuery, where ? aggVars : void 0, m.role, signal, "query")).meta.aggregate.count;
 	}
 	async function upsertDataBody(db, parentId, body, role, signal) {
 		await gql(`mutation UpsertDataBody($object: ${db.table}_insert_input!) {
@@ -608,11 +686,11 @@ function createHasuraDataProvider(config) {
     }`, { object: {
 			[db.fk]: parentId,
 			[db.column]: body
-		} }, role, signal);
+		} }, role, signal, "mutation");
 	}
 	function mutationRecord(m, idField, item, resource, expectedId) {
 		if (item === null || typeof item !== "object" || Array.isArray(item)) throw {
-			kind: "protocol",
+			kind: "not-found",
 			code: "record-not-found",
 			message: `Not found: ${resource}`
 		};
@@ -643,11 +721,11 @@ function createHasuraDataProvider(config) {
 			const where = mergeWhere({ [pkField]: { _eq: id } }, m.fixedFilter);
 			return (await gql(`query One_${m.table}($where: ${m.table}_bool_exp) {
         items: ${m.table}(where: $where, limit: 1) { ${fields} }
-      }`, { where }, m.role, signal)).items?.[0] ?? null;
+      }`, { where }, m.role, signal, "query")).items?.[0] ?? null;
 		}
 		return (await gql(`query One_${m.table}($id: ${pkType}!) {
       item: ${root}(${pkField}: $id) { ${fields} }
-    }`, { id }, m.role, signal)).item;
+    }`, { id }, m.role, signal, "query")).item;
 	}
 	async function listByCursor(m, descriptor, pagination, context) {
 		if (pagination.before !== void 0) throw {
@@ -670,7 +748,7 @@ function createHasuraDataProvider(config) {
       }`;
 		const itemsVars = { limit: pagination.limit + 1 };
 		if (where) itemsVars.where = where;
-		const fetched = (await gql(itemsQuery, itemsVars, m.role, context.signal)).items ?? [];
+		const fetched = (await gql(itemsQuery, itemsVars, m.role, context.signal, "query")).items ?? [];
 		const hasNextPage = fetched.length > pagination.limit;
 		const rows = hasNextPage ? fetched.slice(0, pagination.limit) : fetched;
 		let total;
@@ -715,7 +793,7 @@ function createHasuraDataProvider(config) {
 					offset
 				};
 				if (where) itemsVars.where = where;
-				const itemsData = await gql(itemsQuery, itemsVars, m.role, context.signal);
+				const itemsData = await gql(itemsQuery, itemsVars, m.role, context.signal, "query");
 				let total;
 				const listAggRoot = aggregateRoot(m);
 				if (!m.noAggregate && listAggRoot) try {
@@ -744,7 +822,7 @@ function createHasuraDataProvider(config) {
 				const fields = m.selectFields.join(" ");
 				const data = await gql(`query Many_${m.table}($where: ${m.table}_bool_exp) {
         items: ${m.table}(where: $where) { ${fields} }
-      }`, { where }, m.role, context.signal);
+      }`, { where }, m.role, context.signal, "query");
 				const spill = m.jsonbSpill;
 				return { data: spill ? data.items.map((item) => flattenJsonbSpill(item, spill)) : data.items };
 			},
@@ -761,12 +839,12 @@ function createHasuraDataProvider(config) {
 					const where = mergeWhere(mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter), localeSlice);
 					item = (await gql(`query One_${m.table}($where: ${m.table}_bool_exp) {
           items: ${m.table}(where: $where, limit: 1) { ${fields} }
-        }`, { where }, m.role, context.signal)).items?.[0] ?? null;
+        }`, { where }, m.role, context.signal, "query")).items?.[0] ?? null;
 				} else item = (await gql(`query One_${m.table}($id: ${pkType}!) {
           item: ${root}(${pkField}: $id) { ${fields} }
-        }`, { id: descriptor.id }, m.role, context.signal)).item;
+        }`, { id: descriptor.id }, m.role, context.signal, "query")).item;
 				if (item == null) throw {
-					kind: "protocol",
+					kind: "not-found",
 					code: "record-not-found",
 					message: `Not found: ${descriptor.resource}/${descriptor.id}`
 				};
@@ -802,7 +880,7 @@ function createHasuraDataProvider(config) {
 				const object = m.jsonbSpill ? partitionJsonbSpill(mainInput, m.jsonbSpill, m.selectFields) : mainInput;
 				const data = await gql(`mutation Create_${m.table}($object: ${m.table}_insert_input!) {
         item: insert_${m.table}_one(object: $object) { ${fields} }
-      }`, { object }, m.role, context.signal);
+      }`, { object }, m.role, context.signal, "mutation");
 				const result = mutationRecord(m, descriptor.idField, data.item, descriptor.resource);
 				if (m.dataBody && dataBody) await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
 				return result;
@@ -831,7 +909,7 @@ function createHasuraDataProvider(config) {
         }`, {
 						where,
 						set
-					}, m.role, context.signal);
+					}, m.role, context.signal, "mutation");
 					if (ifUpdatedAt != null && ((data.result.affected_rows ?? 0) === 0 || (data.result.returning?.length ?? 0) === 0)) throw {
 						kind: "conflict",
 						code: "stale-record",
@@ -845,7 +923,7 @@ function createHasuraDataProvider(config) {
         }`, {
 						id: descriptor.id,
 						set
-					}, m.role, context.signal)).item;
+					}, m.role, context.signal, "mutation")).item;
 				}
 				const result = mutationRecord(m, descriptor.idField, item, descriptor.resource, descriptor.id);
 				if (m.dataBody && dataBody) await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
@@ -860,12 +938,12 @@ function createHasuraDataProvider(config) {
 					const where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
 					item = (await gql(`mutation Delete_${m.table}($where: ${m.table}_bool_exp!) {
           result: delete_${m.table}(where: $where) { affected_rows returning { ${fields} } }
-        }`, { where }, m.role, context.signal)).result.returning?.[0] ?? null;
+        }`, { where }, m.role, context.signal, "mutation")).result.returning?.[0] ?? null;
 				} else {
 					const pkType = m.pkType ?? "bigint";
 					item = (await gql(`mutation Delete_${m.table}($id: ${pkType}!) {
           item: delete_${m.table}_by_pk(${pkField}: $id) { ${fields} }
-        }`, { id: descriptor.id }, m.role, context.signal)).item;
+        }`, { id: descriptor.id }, m.role, context.signal, "mutation")).item;
 				}
 				mutationRecord(m, descriptor.idField, item, descriptor.resource, descriptor.id);
 				return {
@@ -889,6 +967,7 @@ function createHasuraDataProvider(config) {
 exports.DEFAULT_HASURA_ENDPOINT = DEFAULT_HASURA_ENDPOINT;
 exports.FILTER_OPERATOR_UNSUPPORTED_CODE = FILTER_OPERATOR_UNSUPPORTED_CODE;
 exports.HASURA_CURSOR_CODES = HASURA_CURSOR_CODES;
+exports.HASURA_EXTERNAL_FAILURE_CODES = HASURA_EXTERNAL_FAILURE_CODES;
 exports.LOCALE_REQUIRED_CODE = LOCALE_REQUIRED_CODE;
 exports.NOT_AUTHENTICATED_CODE = NOT_AUTHENTICATED_CODE;
 exports.aggregateRoot = aggregateRoot;