/apollo-router

Router Customization

Extend Apollo Router functionality with Rhai scripts or external coprocessors.

Customization Options

Rhai Scripts

Rhai is an embedded scripting language for lightweight customizations that run inside the Router.

Enable Rhai

# router.yaml
rhai:
  scripts: ./rhai
  main: main.rhai

Script Location

project/
├── router.yaml
└── rhai/
    ├── main.rhai        # Entry point
    └── helpers.rhai     # Optional modules

Basic Script Structure

// main.rhai

// Called for each incoming request
fn supergraph_service(service) {
    service.map_request(|request| {
        // Modify request
        print(`Received request: ${request.uri.path}`);
    });
}

// Called for each subgraph request
fn subgraph_service(service, subgraph) {
    service.map_request(|request| {
        // Add header for specific subgraph
        if subgraph == "products" {
            request.subgraph.headers["x-products-version"] = "v2";
        }
    });
}

Common Rhai Patterns

Add Request Headers:

fn supergraph_service(service) {
    service.map_request(|request| {
        request.headers["x-custom-header"] = "value";
    });
}

Access JWT Claims:

fn supergraph_service(service) {
    service.map_request(|request| {
        let claims = request.context["apollo_authentication::JWT::claims"];
        if claims != () {
            request.headers["x-user-id"] = claims["sub"];
        }
    });
}

Modify Response:

fn supergraph_service(service) {
    service.map_response(|response| {
        response.headers["x-served-by"] = "apollo-router";
    });
}

Early Return (Reject Request):

fn supergraph_service(service) {
    service.map_request(|request| {
        if request.headers["x-api-key"] == () {
            throw #{
                status: 401,
                message: "API key required"
            };
        }
    });
}

Rhai Hooks

Coprocessors

External HTTP services that process requests/responses at various stages.

Enable Coprocessor

# router.yaml
coprocessor:
  url: http://localhost:8080
  timeout: 2s
  router:
    request:
      headers: true
      body: true
    response:
      headers: true
      body: true

Coprocessor Stages

coprocessor:
  url: http://localhost:8080
  
  # Router-level (full request)
  router:
    request:
      headers: true
      body: true
    response:
      headers: true
      body: false
  
  # Subgraph-level (per subgraph)
  subgraph:
    all:
      request:
        headers: true
        body: false

Coprocessor Request Format

The Router sends POST requests with this structure:

{
  "version": 1,
  "stage": "RouterRequest",
  "control": "continue",
  "id": "request-uuid",
  "headers": {
    "authorization": ["Bearer token"],
    "content-type": ["application/json"]
  },
  "body": "{\"query\": \"{ users { id } }\"}"
}

Coprocessor Response Format

Return JSON to modify the request/response:

{
  "version": 1,
  "stage": "RouterRequest",
  "control": "continue",
  "headers": {
    "x-user-id": ["123"]
  }
}

To reject a request:

{
  "version": 1,
  "stage": "RouterRequest",
  "control": {
    "break": 403
  },
  "body": "{\"errors\": [{\"message\": \"Forbidden\"}]}"
}

Example Coprocessor (Node.js)

const express = require('express');
const app = express();
app.use(express.json());

app.post('/', (req, res) => {
  const { stage, headers, body } = req.body;
  
  // Authentication check
  if (stage === 'RouterRequest') {
    if (!headers.authorization) {
      return res.json({
        version: 1,
        stage,
        control: { break: 401 },
        body: JSON.stringify({
          errors: [{ message: 'Unauthorized' }]
        })
      });
    }
  }
  
  // Continue with optional modifications
  res.json({
    version: 1,
    stage,
    control: 'continue',
    headers: {
      'x-processed-by': ['coprocessor']
    }
  });
});

app.listen(8080);

Choosing Between Rhai and Coprocessors

When to Use Rhai

• Header manipulation
• Simple request/response transformations
• Logging and debugging
• Context value extraction

When to Use Coprocessors

• External API calls (validation, enrichment)
• Complex business logic
• Database lookups
• Integration with existing services
• Team uses a specific language

Native Plugins (Advanced)

For maximum performance, build custom Router binaries with Rust plugins.

# Clone Router
git clone https://github.com/apollographql/router.git

# Create custom plugin in apollo-router/src/plugins/

# Build with custom plugins
cargo build --release

Native plugins require Rust knowledge and a custom build pipeline.