Glean Local Dev Loop

Overview

Local development workflow for Glean enterprise search API integration. Provides a fast feedback loop with mock search results, connector testing, and document indexing simulation so you can build custom datasource connectors and search UIs without needing a live Glean deployment. Toggle between mock mode for rapid connector iteration and sandbox mode for validating against your Glean instance.

Environment Setup

cp .env.example .env
# Set your credentials:
# GLEAN_API_KEY=glean_xxxxxxxxxxxx
# GLEAN_INSTANCE=https://your-company.glean.com
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/api", createProxyMiddleware({
    target: process.env.GLEAN_INSTANCE,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.GLEAN_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3003, () => console.log(`Glean dev server on :3003 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic enterprise search responses
export function mountMockRoutes(app: any) {
  app.post("/api/search", (req: any, res: any) => res.json({
    results: [
      { title: "Q4 Engineering Roadmap", url: "https://wiki.co/roadmap", score: 0.97, datasource: "confluence",
        snippets: [{ snippet: "The <b>roadmap</b> includes migration to..." }] },
      { title: "Onboarding Guide", url: "https://wiki.co/onboard", score: 0.88, datasource: "notion",
        snippets: [{ snippet: "New hire <b>onboarding</b> steps..." }] },
    ],
    totalCount: 2,
  }));
  app.post("/api/index/documents", (req: any, res: any) => res.json({
    status: "OK", documentsIndexed: req.body.documents?.length || 0,
  }));
  app.get("/api/datasources", (_req: any, res: any) => res.json([
    { name: "confluence", displayName: "Confluence", docCount: 1250 },
    { name: "notion", displayName: "Notion", docCount: 430 },
  ]));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real Glean instance

Debug Tips

• Use curl -X POST http://localhost:3003/api/search -d '{"query":"test"}' to verify mock search
• Glean connectors must return documents with id, title, body.textContent, and datasource fields
• Check connector transform output shape before pushing to the indexing API
• Enable verbose logging on the Glean SDK client to trace API call timing
• Verify OAuth scopes if search returns empty results against a live instance

Error Handling

Issue	Cause	Fix
401 Unauthorized	Invalid API key or expired token	Regenerate at Glean admin console
403 Forbidden	Key lacks indexing scope	Request Indexing API permissions from admin
400 Bad Request	Malformed document payload	Validate required fields: id, title, body
429 Rate Limited	Too many indexing requests	Batch documents (max 100 per request)
ECONNREFUSED :3003	Dev server not running	Run npm run dev:mock first

Prerequisites

• A local mock or sandbox endpoint, a fictitious datasource, and no production token in environment files, shell history, or test output.
• A fixture reset command and two synthetic identities for access-boundary tests.
• A change record and rollback path for any configuration that might later be promoted.

Instructions

1. Start in mock mode with bounded fixtures and validate transforms, rejection paths, and redaction before any network call.
2. Use a sandbox datasource with a scoped credential only after local tests pass; assign an idempotency key and verify both allow and deny cases.
3. Keep logs to opaque IDs, status, counts, and correlation values; inspect payloads only in the local fixture directory.
4. Reset fixtures and revoke temporary credentials after the run, then attach a redacted receipt to the change.

Output

Return a local-loop receipt with fixture revision, environment, datasource, tests run, allow/deny outcomes, temporary credential reference, and cleanup state. Exclude tokens, real documents, and search text.

Examples

fixtures=v7; mode=mock->sandbox; source=dev-synthetic; tests=12/12; allow=pass; deny=pass; cleanup=complete is a safe promotion candidate.

Resources

• Glean Indexing API
• Glean Search API

Next Steps

See glean-debug-bundle.