refactor: consolidate fetch infrastructure and enable request batching

- Extract shared batching logic from server to client module
- Rename server files to follow .server.ts convention
- Enable Apollo Server batch operation support
- Configure batch fetcher with 20ms window and max 10 operations
- Eliminate code duplication between client and server fetch implementations

Co-Authored-By: Claude <noreply@anthropic.com>

Author: webberwang

libs/backend/infra/adapter/graphql/src/graphql-client.provider.ts

@@ -79,6 +79,7 @@ export class GraphqlModule {
           ) => {
             return {
               // bodyParserConfig: false,
+              allowBatchedHttpRequests: true,
               context: async ({ req, res }: GqlContext) => {
                 // starting from neo4j/graphql v5 - token is required in order to allow
                 // @authentication/@authorization in neo4j schema files, see migration guide:

libs/backend/infra/adapter/graphql/src/graphql.module.ts

@@ -0,0 +1,54 @@
+# GraphQL Request Batching
+
+## Overview
+
+GraphQL request batching is now built directly into `serverFetchWithAuth`. Multiple GraphQL requests that occur within a time window are automatically combined into a single HTTP request, improving performance and reducing network overhead. This happens transparently - no code changes required!
+
+## How It Works
+
+```typescript
+import { gqlServerRequest } from '@codelab/shared-infra-fetch-server'
+
+// These requests are automatically batched
+const [users, posts, comments] = await Promise.all([
+  gqlServerRequest(GetUsersDocument, { limit: 10 }),
+  gqlServerRequest(GetPostsDocument, { userId: 1 }),
+  gqlServerRequest(GetCommentsDocument, { postId: 1 })
+])
+// These three requests are combined into a single HTTP call!
+```
+
+The batching happens inside `serverFetchWithAuth`:
+1. It detects GraphQL requests by checking for a `query` field in the request body
+2. GraphQL requests are queued and batched within a 20ms window
+3. Up to 10 operations are combined into a single HTTP request
+4. Non-GraphQL requests bypass batching and go directly through
+
+## Configuration
+
+Currently, the batching configuration is fixed at:
+- **Batch interval**: 20ms (time window to collect requests)
+- **Max batch size**: 10 operations per batch
+
+These values are optimized for most use cases and provide a good balance between latency and efficiency.
+
+## Benefits
+
+1. **Reduced Network Overhead**: Fewer HTTP connections and handshakes
+2. **Better Performance**: Especially for pages loading multiple resources
+3. **Efficient Auth Token Usage**: One token retrieval per batch instead of per request
+4. **ECONNRESET Mitigation**: Fewer concurrent connections reduce connection reset errors
+5. **Transparent**: No code changes required for existing `gqlServerRequest` calls
+
+## Implementation Details
+
+- GraphQL requests are automatically detected and batched
+- Non-GraphQL requests (REST APIs, file uploads, etc.) are not affected
+- Authentication is handled once per batch for all operations
+- Each request in a batch maintains its own promise that resolves/rejects independently
+- The batch fetcher uses a singleton pattern for efficiency
+
+## Requirements
+
+- The GraphQL server must support batched queries (Apollo Server supports this by default)
+- Authentication is handled once per batch for all operations

libs/shared/infra/fetch-server/batching.md

@@ -0,0 +1,28 @@
+'use server'
+
+import {
+  batchFetch as clientBatchFetch,
+  configureBatchFetcher,
+  resetBatchFetcher as clientResetBatchFetcher,
+} from '@codelab/shared-infra-fetch'
+import { logger } from '@codelab/shared-infra-logging'
+
+// Configure the batch fetcher with server logger on first import
+configureBatchFetcher({ logger })
+
+/**
+ * Server-side batch fetch wrapper
+ */
+export const batchFetch = async (
+  url: string,
+  init: RequestInit = {},
+): Promise<Response> => {
+  return clientBatchFetch(url, init)
+}
+
+/**
+ * Reset the batch fetcher instance (useful for testing)
+ */
+export const resetBatchFetcher = async () => {
+  clientResetBatchFetcher()
+}

libs/shared/infra/fetch-server/src/batch-fetch.server.ts

@@ -0,0 +1,13 @@
+'use server'
+
+import { fetchWithAuth } from '@codelab/shared-infra-fetch'
+
+/**
+ * Server-side fetch with authentication wrapper
+ */
+export const serverFetchWithAuth = async (
+  endpoint: string,
+  init: RequestInit,
+): Promise<Response> => {
+  return fetchWithAuth(endpoint, init)
+}

libs/shared/infra/fetch-server/src/fetch-with-auth.server.ts

@@ -11,7 +11,7 @@ import { logger } from '@codelab/shared-infra-logging'
 import { TRACING_HEADERS } from '@codelab/shared-infra-tracing'
 import { revalidateTag } from 'next/cache'
 
-import { serverFetchWithAuth } from './server-fetch-with-auth'
+import { serverFetchWithAuth } from './fetch-with-auth.server'
 
 /**
  * Server-side GraphQL request function that handles authentication and logging.

libs/shared/infra/fetch-server/src/gql-server-request.ts renamed to libs/shared/infra/fetch-server/src/gql-request.server.ts

@@ -1,2 +1,3 @@
-export { gqlServerRequest } from './gql-server-request'
-export * from './server-fetch-with-auth'
+export { resetBatchFetcher } from './batch-fetch.server'
+export * from './fetch-with-auth.server'
+export { gqlServerRequest } from './gql-request.server'