@carvajalconsultants/headstart 1.0.5 → 1.0.6

package/README.md

@@ -16,15 +16,15 @@ This library is made up of:
    Specifically, the `graphile.config.ts` and `pgl.ts`. If you need WebSocket support, make sure to add a plugin in `graphile.config.ts` as per: https://postgraphile.org/postgraphile/next/subscriptions
 
 3. Install Headtart & URQL:
-```
-yarn add @carvajalconsultants/headstart urql @urql/exchange-graphcache
+```bash
+yarn add @carvajalconsultants/headstart urql @urql/exchange-graphcache @urql/exchange-auth
 ```
 
 4. Enable WebSockets in `app.config.ts` if you need it:
 
-```
+```typescript
 // app.config.ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "@tanstack/react-start/config";
 
 export default defineConfig({
 	server: {
@@ -37,7 +37,7 @@ export default defineConfig({
 
 5. Make sure to add the `/api` endpoint to the grafserv configuration so that Ruru GraphQL client works correctly:
 
-```
+```typescript
 // graphile.config.ts
 const preset: GraphileConfig.Preset = {
     ...
@@ -52,9 +52,9 @@ const preset: GraphileConfig.Preset = {
 
 6. Add the api.ts file so that it calls our GraphQL handler. This will receive all GraphQL requests at the /api endpoint.
 
-```
+```typescript
 // app/api.ts
-import { defaultAPIFileRouteHandler } from "@tanstack/start/api";
+import { defaultAPIFileRouteHandler } from "@tanstack/react-start/api";
 import { createStartAPIHandler } from "@carvajalconsultants/headstart/server";
 import { pgl } from "../pgl";
 
@@ -63,7 +63,7 @@ export default createStartAPIHandler(pgl, defaultAPIFileRouteHandler);
 
 7. Now we need to configure URQL for client and server rendering, first we start with the server. Create this provider:
 
-```
+```typescript
 // app/graphql/serverProvider.tsx
 import { Client } from "urql";
 import { grafastExchange } from "@carvajalconsultants/headstart/server";
@@ -81,9 +81,90 @@ export const client = new Client({
 });
 ```
 
-8. Create the server side router which uses Grafast to execute queries:
+8. Now the client side for URQL:
+
+```typescript
+// app/graphql/clientProvider.tsx
+import { ssr } from "@carvajalconsultants/headstart/client";
+import { authExchange } from "@urql/exchange-auth";
+import { cacheExchange } from "@urql/exchange-graphcache";
+//import { relayPagination } from "@urql/exchange-graphcache/extras";
+import { Client, fetchExchange } from "urql";
 
+/**
+ * Creates an authentication exchange for handling secure GraphQL operations.
+ * This exchange ensures that all GraphQL requests are properly authenticated
+ * and handles authentication failures gracefully.
+ *
+ * @returns {Object} Authentication configuration object
+ * @returns {Function} .addAuthToOperation - Prepares operations with auth context
+ * @returns {Function} .didAuthError - Detects authentication failures after server request
+ * @returns {Function} .refreshAuth - Handles auth token refresh
+ */
+const auth = authExchange(async () => {
+  //TODO Implement authentication checking for the client s ide
+  await new Promise((resolve) => {
+    setTimeout(() => {
+      console.log("IMPLEMENT CLIENT AUTH CHECK");
+      resolve();
+    }, 2000);
+  });
+
+  return {
+    /**
+     * Processes each GraphQL operation to include authentication context.
+     * Currently configured as a pass-through as tokens are in cookies.
+     *
+     * @param {Operation} operation - The GraphQL operation to authenticate
+     * @returns {Operation} The operation with authentication context
+     */
+    addAuthToOperation: (operation) => operation,
+
+    /**
+     * Identifies when an operation has failed due to authentication issues.
+     * Used to trigger authentication refresh flows when needed.
+     *
+     * @param {Error} error - The GraphQL error response
+     * @returns {boolean} True if the error was caused by authentication failure
+     */
+    didAuthError: (error) => error.graphQLErrors.some((e) => e.extensions?.code === "FORBIDDEN"),
+
+    /**
+     * Handles refreshing authentication when it becomes invalid.
+     * Currently implemented as a no-op as token refresh is handled by getSession().
+     */
+    refreshAuth: async () => {
+      /* No-op, this is done in getSession() */
+    },
+  };
+});
+
+/**
+ * Configured GraphQL client for the application.
+ * Provides a centralized way to make authenticated GraphQL requests with
+ * proper caching and server-side rendering support.
+ */
+export const client = new Client({
+  url: "http://localhost:3000/api/graphql",
+  exchanges: [
+    cacheExchange({
+      resolvers: {
+        Query: {
+          // Implements relay-style pagination for fills pending match
+          //queryName: relayPagination(),
+        },
+      },
+    }),
+    auth,
+    ssr,
+    fetchExchange,
+  ],
+});
 ```
+
+9. Create the server side router which uses Grafast to execute queries:
+
+```typescript
 // app/serverRouter.tsx
 import { ssr } from "@carvajalconsultants/headstart/client";
 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
@@ -91,6 +172,8 @@ import { Provider } from "urql";
 import { client } from "./graphql/serverProvider";
 import { routeTree } from "./routeTree.gen";
 
+import type { ReactNode } from "react";
+
 export function createRouter() {
 	const router = createTanStackRouter({
 		routeTree,
@@ -101,20 +184,21 @@ export function createRouter() {
 		// Send data to client so URQL can be hydrated.
 		dehydrate: () => ({ initialData: ssr.extractData() }),
 
-        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
-		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+		// Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }: { children: ReactNode }) => <Provider value={client}>{children}</Provider>,
 	});
 
 	return router;
 }
 ```
 
-9. Modify the TSR server-side rendering function to use this new router:
+10. Modify the TSR server-side rendering function to use this new router:
 
-```
+```typescript
+/* eslint-disable */
 // app/ssr.tsx
 /// <reference types="vinxi/types/server" />
-import { getRouterManifest } from "@tanstack/start/router-manifest";
+import { getRouterManifest } from "@tanstack/react-start/router-manifest";
 import {
 	createStartHandler,
 	defaultStreamHandler,
@@ -128,9 +212,9 @@ export default createStartHandler({
 })(defaultStreamHandler);
 ```
 
-10. Add the client side router which uses the fetch exchange to execute queries, mutations, etc.:
+11. Add the client side router which uses the fetch exchange to execute queries, mutations, etc.:
 
-```
+```typescript
 // app/clientRouter.tsx
 import { ssr } from "@carvajalconsultants/headstart/client";
 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
@@ -138,6 +222,9 @@ import { Provider } from "urql";
 import { client } from "./graphql/clientProvider";
 import { routeTree } from "./routeTree.gen";
 
+import type { ReactNode } from "react";
+import type { SSRData } from "urql";
+
 export function createRouter() {
 	const router = createTanStackRouter({
 		routeTree,
@@ -146,20 +233,20 @@ export function createRouter() {
 		},
 		hydrate: (dehydrated) => {
 			// Hydrate URQL with data passed by TSR, this is generated by dehydrate function in server router.
-			ssr.restoreData(dehydrated.initialData);
+			ssr.restoreData(dehydrated.initialData as SSRData);
 		},
 
-        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
-		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+		// Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }: { children: ReactNode }) => <Provider value={client}>{children}</Provider>,
 	});
 
 	return router;
 }
 ```
 
-11. Tell TSR to use our client side router:
+12. Tell TSR to use our client side router:
 
-```
+```typescript
 // app/client.tsx
 /// <reference types="vinxi/types/client" />
 import { StartClient } from "@tanstack/start";
@@ -171,9 +258,9 @@ const router = createRouter();
 hydrateRoot(document.getElementById("root")!, <StartClient router={router} />);
 ```
 
-12. Last but not least, you're ready to start using URQL on your components and pages. First we create the route using the loader option so we can pre-load data:
+13. Last but not least, you're ready to start using URQL on your components and pages. First we create the route using the loader option so we can pre-load data:
 
-```
+```typescript
 export const Route = createFileRoute("/")({
 	...
 	validateSearch: zodSearchValidator(paramSchema),
@@ -188,9 +275,9 @@ export const Route = createFileRoute("/")({
 });
 ```
 
-13. Now in your component, you can query with URQL as you normally would:
+14. Now in your component, you can query with URQL as you normally would:
 
-```
+```typescript
 const Home = () => {
 	const { page } = Route.useSearch();
 
@@ -209,8 +296,8 @@ const Home = () => {
 
 ## Deployment
 
-1. Run `bun run build`
+1. Run `yarn run build`
 2. `cd .output/server`
 3. `rm -rf node_modules`
-4. `bun install`
-5. `bun run index.mjs`
+4. `yarn install`
+5. `yarn run index.mjs`

package/grafastExchange.ts

@@ -6,9 +6,18 @@ import {
 	type OperationResult,
 } from "urql";
 import { filter, fromPromise, mergeMap, pipe } from "wonka";
+import type { App, H3Event } from "h3";
+import {
+  getQuery,
+  getRequestHeaders,
+  getRequestProtocol,
+  readRawBody,
+} from "h3";
 
 import type { Maybe } from "grafast";
 import type { PostGraphileInstance } from "postgraphile";
+import { getEvent, getWebRequest } from "vinxi/http";
+import { GrafservBodyBuffer, normalizeRequest, processHeaders, RequestDigest } from "postgraphile/grafserv";
 
 export const grafastExchange = (pgl: PostGraphileInstance): Exchange => {
 	return () => (ops$) => {
@@ -16,13 +25,49 @@ export const grafastExchange = (pgl: PostGraphileInstance): Exchange => {
 			ops$,
 
 			// Skip anything that's not a query since that's all we can run
-			filter((operation) => operation.kind === "query"),
+			filter((operation) => operation.kind === "query" || operation.kind === "mutation"),
 
 			mergeMap((operation) => fromPromise(runGrafastQuery(pgl, operation))),
 		);
 	};
 };
 
+/* This is a direct copy from: https://github.com/graphile/crystal/blob/main/grafast/grafserv/src/servers/h3/v1/index.ts#L24 */
+function getDigest(event: H3Event): RequestDigest {
+  const req = event.node.req;
+  const res = event.node.res;
+  return {
+    httpVersionMajor: req.httpVersionMajor,
+    httpVersionMinor: req.httpVersionMinor,
+    isSecure: getRequestProtocol(event) === "https",
+    method: event.method,
+    path: event.path,
+    headers: processHeaders(getRequestHeaders(event)),
+    getQueryParams() {
+      return getQuery(event) as Record<string, string | string[]>;
+    },
+    async getBody() {
+      const buffer = await readRawBody(event, false);
+      if (!buffer) {
+        throw new Error("Failed to retrieve body from h3");
+      }
+      return {
+        type: "buffer",
+        buffer,
+      } as GrafservBodyBuffer;
+    },
+    requestContext: {
+      h3v1: {
+        event,
+      },
+      node: {
+        req,
+        res,
+      },
+    },
+  };
+}
+
 /**
  * Run the URQL query with Grafast, without making an HTTP request to ourselves (which is unnecessary overhead).
  *
@@ -37,16 +82,25 @@ const runGrafastQuery = async (
 	try {
 		const { variables: variableValues, query: document } = operation;
 
-		const args = {
-			resolvedPreset: pgl.getResolvedPreset(),
-			schema: await pgl.getSchema(),
+		const { schema, resolvedPreset } = await pgl.getSchemaResult();
+
+		// Request/H3 info so we can run with it
+		const event = await getEvent();
+		const http = normalizeRequest(getDigest(event));
+
+		// Add the Graphile context to our args so Grafast can run
+		const args = await hookArgs({
+			schema,
 			document,
 			variableValues: variableValues as Maybe<{
 				readonly [variable: string]: unknown;
 			}>,
-		};
-		// Add the Graphile context to our args so Grafast can run
-		await hookArgs(args);
+			resolvedPreset,
+			requestContext: {
+				...http.requestContext,
+				http,
+			}
+		});
 
 		// Run the query with Grafast, to get the result from PostgreSQL
 		const result = await execute(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carvajalconsultants/headstart",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Library to assist in integrating PostGraphile with Tanstack Start and URQL.",
   "license": "MIT",
   "author": "Miguel Carvajal <omar@carvajalonline.com>",