Skip to content

index.md

Latest commit

 

History

History
195 lines (140 loc) · 3.72 KB

index.md

File metadata and controls

195 lines (140 loc) · 3.72 KB
Raw

Getting Started

Quick start guide for the GraphQL proxy server.

Overview

This GraphQL proxy server acts as an intermediary between your applications and upstream GraphQL APIs. It provides caching, offline mutation queuing, and local data synchronization capabilities.

Prerequisites

  • Node.js 18+ or Bun
  • Access to an upstream GraphQL API

Quick Setup

1. Install Dependencies

# Using npm
npm install

# Using bun (recommended)
bun install

2. Configure Environment

Create a .env file:

# Required: Your upstream GraphQL endpoint
UPSTREAM_GRAPHQL_ENDPOINT=https://api.example.com/graphql

# Optional: Authentication token
AUTH_TOKEN=your-auth-token

# Optional: Custom port (default: 5001)
PORT=5001

# Optional: GraphQL mode (default: GETMODE)
GRAPHQL_MODE=SETMODE

3. Start the Server

# Development mode
bun run dev

# Production mode
bun run start

The server will start on http://localhost:5001.

Basic Usage

Health Check

Verify the server is running:

curl http://localhost:5001/health

Response:

{
  "ok": true,
  "port": 5001,
  "mode": "SETMODE",
  "upstream": "configured"
}

GraphQL Queries

Send GraphQL queries to the proxy:

curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { posts { id title } }"
  }'

GraphQL Mutations (SETMODE)

In SETMODE, mutations are executed when online and queued when offline:

curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { createPost(input: { title: \"Hello\" }) { post { id } } }"
  }'

Configuration Examples

Read-Only Proxy (GETMODE)

UPSTREAM_GRAPHQL_ENDPOINT=https://api.example.com/graphql
GRAPHQL_MODE=GETMODE
  • ✅ Queries: Cached proxy to upstream
  • ❌ Mutations: Blocked

Offline-Capable Proxy (SETMODE)

UPSTREAM_GRAPHQL_ENDPOINT=https://api.example.com/graphql
AUTH_TOKEN=your-token
GRAPHQL_MODE=SETMODE
  • ✅ Queries: Cached proxy to upstream
  • ✅ Mutations: Execute online, queue offline
  • ✅ Local DB: Syncs with mutations

Development Setup

# .env.development
UPSTREAM_GRAPHQL_ENDPOINT=http://localhost:4000/graphql
PORT=5001
GRAPHQL_MODE=SETMODE
DEBUG=true

Testing the Setup

1. Test GraphQL Endpoint

# Simple introspection query
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

2. Test Caching

# First request (cache miss)
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "query { posts { id } }"}' \
  -v

# Second request (cache hit)
curl -X POST http://localhost:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "query { posts { id } }"}' \
  -v

Look for x-cache: HIT in the response headers.

3. Test Local Data Sync

# Sync local database from upstream
curl -X POST http://localhost:5001/local/sync

# View local data
curl http://localhost:5001/local/data

Docker Deployment

For production deployment, use Docker:

# Build image
docker build -t graphql-proxy .

# Run container
docker run -d \
  --name graphql-proxy \
  -p 5001:5001 \
  -e UPSTREAM_GRAPHQL_ENDPOINT=https://api.example.com/graphql \
  -e GRAPHQL_MODE=SETMODE \
  graphql-proxy

Next Steps