Added new feature for document export
This commit is contained in:
156
specs/001-sitemap/plan.md
Normal file
156
specs/001-sitemap/plan.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Implementation Plan: Google Drive HTTP Proxy Adapter
|
||||
|
||||
**Branch**: `001-drive-proxy-adapter` | **Date**: 2026-03-07 | **Spec**: [spec.md](./spec.md)
|
||||
**Input**: Feature specification from `/specs/001-drive-proxy-adapter/spec.md`
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
|
||||
|
||||
## Summary
|
||||
|
||||
Build a Node.js HTTP server that provides a single `/sitemap.xml` endpoint to generate XML sitemaps of Google Drive documents. The system authenticates using a Service Account (JWT-based), queries the Drive API for accessible documents, and returns a sitemap with RESTful URLs (`/documents/{documentId}`). Key features include: FIFO request queuing for concurrent requests, configurable Drive API filters via config/settings.js, 413 error handling for >50k documents, plain text logging to stdout/stderr, and immediate crash (exit code 1) on fatal errors. All clarifications from 3 sessions (10 total Q&A pairs) are now incorporated into design.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: JavaScript ES2022+ (Node.js LTS v18.0.0+)
|
||||
**Primary Dependencies**:
|
||||
|
||||
- `googleapis` v140.0.0 (Google Drive API client - justified: official Google SDK, handles OAuth2/JWT complexity, Drive API protocol implementation)
|
||||
- Node.js built-ins: `http`, `fs`, `path`, `events` (for FIFO queue)
|
||||
**Storage**: N/A (no persistence - sitemap generated on-demand from Drive API)
|
||||
**Testing**: Node.js native test runner (`node:test`) with unit, integration, and contract test suites
|
||||
**Target Platform**: Linux/macOS server environment, containerizable
|
||||
**Project Type**: Web service (HTTP proxy adapter with monolithic route architecture)
|
||||
**Performance Goals**:
|
||||
- `/sitemap.xml` response < 5 seconds for drives with ≤10k documents
|
||||
- Handle 10 concurrent requests (queued FIFO, processed sequentially)
|
||||
- Startup time < 10 seconds (cold start to accepting requests)
|
||||
**Constraints**:
|
||||
- Memory usage < 256MB under normal load
|
||||
- No file-based logging (stdout/stderr only)
|
||||
- No retries on Drive API 503 errors (fail immediately)
|
||||
- 50,000 document limit (sitemap protocol constraint)
|
||||
- FIFO queue for /sitemap.xml requests (one at a time to prevent concurrent Drive API operations)
|
||||
**Scale/Scope**:
|
||||
- Single endpoint (`/sitemap.xml`)
|
||||
- Support up to 50k Drive documents (enforced limit)
|
||||
- 95% success rate for sitemap requests
|
||||
- Service Account JWT token refresh automatically
|
||||
|
||||
## Constitution Check
|
||||
|
||||
_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
|
||||
|
||||
### ✅ I. Monolithic Architecture
|
||||
|
||||
- **Status**: COMPLIANT
|
||||
- **Rationale**: All proxy logic in `src/proxy.js`, routed from `src/server.js`. Configuration in `config/settings.js` (Drive API filter), loaded into global `settings`. Logging uses `src/console.js` (aliased as `console.js` with log/info/debug/error functions).
|
||||
- **Phase 1 Verification**: data-model.md confirms stateless architecture, no persistence layer. All entities are runtime structures (Document, SitemapEntry, HTTPRequestContext, RequestQueue). Monolithic route pattern maintained.
|
||||
|
||||
### ✅ II. API-First Design
|
||||
|
||||
- **Status**: COMPLIANT
|
||||
- **Rationale**: Single API endpoint `/sitemap.xml` fully specified in spec.md with RESTful URL format, HTTP status codes (200, 404, 413, 429, 503), and XML response format (sitemap protocol). Error handling documented (no response body, status codes only).
|
||||
- **Phase 1 Verification**: contracts/sitemap-xml-schema.md provides complete API contract with request/response formats, XML schema requirements, validation criteria, and version history. quickstart.md documents API usage with examples.
|
||||
|
||||
### ⚠️ III. Test-First Development (NON-NEGOTIABLE)
|
||||
|
||||
- **Status**: TO BE VERIFIED IN PHASE 2
|
||||
- **Action Required**: Tasks.md must include test-first workflow:
|
||||
1. Write failing unit tests for Drive API client, JWT auth, sitemap generator
|
||||
2. Write failing integration tests for /sitemap.xml endpoint (200, 413, 429, 503 scenarios)
|
||||
3. Write failing contract tests for XML sitemap format validation
|
||||
4. Obtain user approval of test scenarios before implementation
|
||||
5. Implement minimum code to pass tests (80%+ coverage requirement)
|
||||
- **Phase 1 Note**: Test structure defined in plan.md (tests/unit/, tests/integration/, tests/contract/) and quickstart.md documents test execution commands.
|
||||
|
||||
### ✅ IV. Security & Privacy by Default
|
||||
|
||||
- **Status**: COMPLIANT
|
||||
- **Rationale**: Service Account credentials loaded from `GOOGLE_SERVICE_ACCOUNT_KEY` env var (inline JSON), never logged. JWT tokens handled by googleapis SDK. No user data stored (stateless sitemap generation). Drive API read-only scope (`https://www.googleapis.com/auth/drive.readonly`).
|
||||
- **Phase 1 Verification**: data-model.md includes security note on ServiceAccountCredentials entity: "NEVER log private_key field, mask client_email in logs". quickstart.md documents security best practices section.
|
||||
|
||||
### ✅ V. Observability & Debuggability
|
||||
|
||||
- **Status**: COMPLIANT
|
||||
- **Rationale**: Plain text logging format `[timestamp] [level] message` to stdout/stderr. Request logging includes endpoint + response status. Error logging includes error messages for debugging. Fatal errors logged to stderr before crashing with exit code 1.
|
||||
- **Phase 1 Verification**: research.md Section 5 details logging implementation with formatMessage function and log event capture list. data-model.md includes HTTPRequestContext entity with requestId for tracing.
|
||||
|
||||
### ✅ VI. Semantic Versioning & Change Management
|
||||
|
||||
- **Status**: COMPLIANT
|
||||
- **Rationale**: package.json at v1.0.0. Single endpoint API `/sitemap.xml` - breaking changes would require version bump and migration guide. Sitemap XML format follows public sitemap protocol standard.
|
||||
- **Phase 1 Verification**: contracts/sitemap-xml-schema.md includes "Breaking Changes" section defining what constitutes MAJOR version bump. Version history table tracks changes. quickstart.md versioned at 1.0.0.
|
||||
|
||||
### ✅ VII. Simplicity, Minimal Dependencies & YAGNI
|
||||
|
||||
- **Status**: COMPLIANT WITH JUSTIFICATION
|
||||
- **Dependencies**:
|
||||
- ✅ `googleapis@140.0.0` - **JUSTIFIED**: Official Google SDK, handles complex OAuth2/JWT flow, implements Drive API v3 protocol, active maintenance. Alternative (manual JWT + REST calls) would take >2 days and risk protocol errors.
|
||||
- ✅ Node.js built-ins: `http` (server), `fs` (config loading), `path` (file paths), `events` (FIFO queue via EventEmitter), `crypto` (randomUUID for request tracing)
|
||||
- **No speculative features**: Only implements /sitemap.xml endpoint (document export removed from scope in Session 2). No caching, no health checks, no admin UI.
|
||||
- **YAGNI applied**: Rejected retry logic (per spec: fail immediately on 503), rejected file logging (stdout/stderr only), rejected concurrent processing (FIFO queue mandated).
|
||||
- **Phase 1 Verification**: research.md Section 6 documents Technology Stack Validation - confirms only googleapis as external dependency. data-model.md uses only built-in types (no ORM, no database). quickstart.md confirms minimal dependencies section.
|
||||
|
||||
### Constitution Check Summary (Post-Phase 1)
|
||||
|
||||
- **PASS**: All 7 constitutional principles satisfied after Phase 1 design
|
||||
- **Action Items**: Phase 2 tasks.md must enforce TDD workflow with test approval gate
|
||||
- **Design Artifacts Complete**:
|
||||
- ✅ research.md - All technical unknowns resolved
|
||||
- ✅ data-model.md - Entities, state machines, validation rules documented
|
||||
- ✅ contracts/sitemap-xml-schema.md - Complete API contract with examples
|
||||
- ✅ quickstart.md - Installation, configuration, usage, troubleshooting guide
|
||||
- ✅ Agent context updated - Copilot instructions.md includes language/database/project type
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/001-drive-proxy-adapter/
|
||||
├── plan.md # This file (/speckit.plan command output)
|
||||
├── research.md # Phase 0 output (/speckit.plan command)
|
||||
├── data-model.md # Phase 1 output (/speckit.plan command)
|
||||
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
||||
├── contracts/ # Phase 1 output (/speckit.plan command)
|
||||
│ └── sitemap-xml-schema.md
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
# Single project - Monolithic proxy architecture (per Constitution Principle I)
|
||||
src/
|
||||
├── server.js # HTTP server entry point, routes all requests to proxy.js
|
||||
├── proxy.js # Monolithic route handler (all sitemap logic inline)
|
||||
├── console.js # Logging module (console.js alias: log/info/debug/error)
|
||||
├── auth.js # Service Account JWT authentication (googleapis wrapper)
|
||||
├── utils.js # Inline utility functions (if needed - prefer inline in proxy.js)
|
||||
└── xml-utils.js # XML generation utilities (sitemap format)
|
||||
|
||||
config/
|
||||
├── config.js # Server configuration (port, base URL) - JSON export
|
||||
└── settings.js # Drive API query filter configuration - loaded into global `settings`
|
||||
|
||||
tests/
|
||||
├── contract/ # XML sitemap format validation tests
|
||||
│ └── sitemap-schema.test.js
|
||||
├── integration/ # End-to-end /sitemap.xml endpoint tests
|
||||
│ ├── sitemap-endpoint.test.js
|
||||
│ ├── error-scenarios.test.js
|
||||
│ └── queue-concurrency.test.js
|
||||
└── unit/ # Unit tests for Drive API client, JWT, sitemap generator
|
||||
├── drive-client.test.js
|
||||
├── auth.test.js
|
||||
├── sitemap-generator.test.js
|
||||
└── queue.test.js
|
||||
```
|
||||
|
||||
**Structure Decision**: Single project with monolithic architecture. All proxy logic consolidated in `src/proxy.js` per Constitution Principle I. The `server.js` routes all requests to `proxy.js`. Configuration split between `config/config.js` (server settings) and `config/settings.js` (Drive API filter - loaded into global `settings` variable). Testing organized by contract/integration/unit layers to support TDD workflow (Constitution Principle III).
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||||
|
||||
**NO VIOLATIONS** - All constitutional principles satisfied. No complexity justification required.
|
||||
Reference in New Issue
Block a user