feat: Add X-Verint-KAB-Original-URL header to document exports
Adds HTTP response header containing original Google Drive URL for exported documents to enable content traceability and auditing. - Adds X-Verint-KAB-Original-URL header to successful export responses - Header format: https://drive.google.com/file/d/{fileId} - Present for all export formats (PDF, DOCX, plain text) - Header omitted on error responses (4xx/5xx) - 18 new tests (9 contract + 9 integration) - Zero new dependencies - Performance: 0.000019ms overhead per request Implements: - FR-001: Header present on successful exports (200 OK) - FR-002: Header absent on error responses - FR-003: Standard header name X-Verint-KAB-Original-URL - FR-004: Standard URL format with file ID - FR-005: Uses validated document.id from Google Drive API - FR-006: Header present regardless of file accessibility - FR-007: Consistent across all export formats - FR-008: Minimal performance impact (< 5ms requirement) Testing: - Contract tests validate header presence, format, and error handling - Integration tests verify behavior across formats and permissions - All 18 tests passing - 100% requirements coverage Documentation: - Feature specification (specs/001-gdrive-url-header/spec.md) - Implementation plan (plan.md) - Technical research (research.md) - Data model (data-model.md) - API contract (contracts/response-headers.md) - User guide (quickstart.md) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
178
specs/001-gdrive-url-header/plan.md
Normal file
178
specs/001-gdrive-url-header/plan.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# Implementation Plan: Google Drive Original URL Header
|
||||
|
||||
**Branch**: `001-gdrive-url-header` | **Date**: 2026-03-27 | **Spec**: [spec.md](./spec.md)
|
||||
**Input**: Feature specification from `/specs/001-gdrive-url-header/spec.md`
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
|
||||
|
||||
## Summary
|
||||
|
||||
Add HTTP response header `X-Verint-KAB-Original-URL` to all document export responses, containing the original Google Drive URL for traceability and auditing. The implementation will modify the existing proxy.js request handler to construct and include the Google Drive URL based on the document's file ID, ensuring consistent header presence across all export formats with minimal performance overhead (< 5ms).
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Node.js 18+ (ES2022+ JavaScript, no TypeScript)
|
||||
**Primary Dependencies**: axios (HTTP client), jsonwebtoken (JWT), xmlbuilder2 (XML generation), uuid (UUID generation)
|
||||
**Storage**: N/A (stateless HTTP service)
|
||||
**Testing**: node:test (native Node.js test runner)
|
||||
**Target Platform**: Linux server / Docker container
|
||||
**Project Type**: HTTP web service (Google Drive content adapter/proxy)
|
||||
**Performance Goals**: < 5ms overhead per request, support concurrent requests without degradation
|
||||
**Constraints**: Monolithic architecture (all business logic in src/proxyScripts/proxy.js), VM isolation via vm.Script, zero imports/exports in proxy.js
|
||||
**Scale/Scope**: Single-purpose service handling document export requests with header addition
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
### Core Architecture Compliance
|
||||
|
||||
✅ **Monolithic Architecture**: Feature adds header logic within existing src/proxyScripts/proxy.js (no new files)
|
||||
✅ **Zero Imports/Exports**: Implementation will modify proxy.js without introducing any imports or exports
|
||||
✅ **VM Isolation**: Changes remain within existing vm.Script execution context
|
||||
✅ **Helper Extraction**: URL construction is simple enough to stay in proxy.js (no helper extraction needed)
|
||||
|
||||
### Dependency Budget
|
||||
|
||||
✅ **No New Dependencies**: Implementation uses existing capabilities (string formatting, existing Google Drive file ID access)
|
||||
✅ **Node.js Built-ins Preferred**: Uses standard JavaScript string operations only
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
✅ **TDD Workflow**: Tests will be written before implementation
|
||||
✅ **80% Coverage Target**: New code will be covered by contract and unit tests
|
||||
✅ **Test Structure**: Contract tests for header presence, unit tests for URL construction logic
|
||||
|
||||
### API Contract Consistency
|
||||
|
||||
✅ **Header Addition**: Adding response header is non-breaking (clients can ignore unknown headers)
|
||||
✅ **No Breaking Changes**: Does not modify existing response body or behavior
|
||||
✅ **Consistent Behavior**: Header will be present on all export responses (success cases)
|
||||
|
||||
### Security & Data Protection
|
||||
|
||||
✅ **No Credentials Exposed**: Google Drive URLs are public identifiers (file IDs), not sensitive data
|
||||
✅ **Input Validation**: Will validate file ID format before constructing URL
|
||||
✅ **No New Attack Surface**: Header value is constructed server-side, not from user input
|
||||
|
||||
### Performance Impact
|
||||
|
||||
✅ **< 5ms Overhead**: String formatting and header assignment is negligible
|
||||
✅ **No Additional API Calls**: Uses file ID already available from existing Drive API response
|
||||
✅ **No Memory Impact**: Single string per request, immediately garbage collected
|
||||
|
||||
**Result: ALL GATES PASS ✅**
|
||||
|
||||
No constitutional violations. Feature aligns with all architectural principles and quality requirements.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/001-gdrive-url-header/
|
||||
├── 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)
|
||||
│ └── response-headers.md # HTTP response header contract
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
src/
|
||||
├── proxyScripts/
|
||||
│ └── proxy.js # MODIFIED: Add X-Verint-KAB-Original-URL header logic
|
||||
├── globalVariables/
|
||||
│ ├── googleDriveAdapterHelper.js # No changes (unless URL construction helper added)
|
||||
│ └── google_drive_settings.json # No changes
|
||||
├── logger.js # No changes
|
||||
└── server.js # No changes
|
||||
|
||||
tests/
|
||||
├── contract/
|
||||
│ └── response-headers.test.js # NEW: Test header presence and format
|
||||
├── integration/
|
||||
│ └── header-integration.test.js # NEW: Test with real Drive API responses
|
||||
└── unit/
|
||||
└── url-construction.test.js # NEW: Test URL construction logic
|
||||
|
||||
config/
|
||||
└── default.json # No changes (infrastructure only)
|
||||
```
|
||||
|
||||
**Structure Decision**: All implementation changes confined to `src/proxyScripts/proxy.js` following the monolithic architecture principle. URL construction logic will be added inline within the export response handler. No new files needed except tests. The feature leverages existing Drive API file ID extraction and adds minimal header-setting logic.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
No constitutional violations identified. This section is not applicable.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 Design Complete - Constitution Re-Check
|
||||
|
||||
**Date**: 2026-03-27
|
||||
**Status**: ✅ ALL GATES PASS
|
||||
|
||||
### Post-Design Validation
|
||||
|
||||
After completing research.md, data-model.md, contracts/, and quickstart.md, re-validation confirms:
|
||||
|
||||
✅ **No New Architecture Concerns**:
|
||||
- Implementation location confirmed (proxy.js lines 377-383)
|
||||
- URL construction is simple string interpolation
|
||||
- No helper function needed
|
||||
|
||||
✅ **No New Dependencies**:
|
||||
- Confirmed: only standard JavaScript operations
|
||||
- No npm packages required
|
||||
- No Node.js modules needed beyond what's already available
|
||||
|
||||
✅ **API Contract Well-Defined**:
|
||||
- contracts/response-headers.md provides complete specification
|
||||
- Header format: `https://drive.google.com/file/d/{fileId}`
|
||||
- Presence rules clearly defined (success only)
|
||||
|
||||
✅ **Testing Strategy Clear**:
|
||||
- Contract tests for header presence/format
|
||||
- Integration tests with Drive API
|
||||
- No unit tests needed (too simple)
|
||||
|
||||
✅ **Performance Validated**:
|
||||
- Research confirms < 1ms overhead (well within 5ms requirement)
|
||||
- Single string concatenation operation
|
||||
- ~100 bytes memory per request
|
||||
|
||||
✅ **Implementation Path Validated**:
|
||||
- Exact code location identified (proxy.js line 377 or 383)
|
||||
- Uses validated `document.id` from API response
|
||||
- Omits header on error paths (cleaner contract)
|
||||
|
||||
**Final Result**: Feature design passes all constitutional requirements. Ready for Phase 2 (task breakdown).
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Run `/speckit.tasks`** to generate actionable task breakdown (tasks.md)
|
||||
2. **Execute tasks** via `/speckit.implement` or manual implementation
|
||||
3. **TDD workflow**: Write tests first, then implement
|
||||
4. **Validate**: Ensure all acceptance criteria from spec.md are met
|
||||
|
||||
---
|
||||
|
||||
## Summary of Artifacts Generated
|
||||
|
||||
| Artifact | Status | Description |
|
||||
|----------|--------|-------------|
|
||||
| plan.md | ✅ Complete | This file - implementation plan and architecture |
|
||||
| research.md | ✅ Complete | Research findings for URL format, ID availability, header patterns |
|
||||
| data-model.md | ✅ Complete | Data flow and entity descriptions (HTTP header, URL construction) |
|
||||
| contracts/response-headers.md | ✅ Complete | API contract for X-Verint-KAB-Original-URL header |
|
||||
| quickstart.md | ✅ Complete | User guide with examples and client integration code |
|
||||
| tasks.md | ⏳ Pending | To be generated by `/speckit.tasks` command |
|
||||
|
||||
**Implementation Ready**: All design artifacts complete. Feature is ready for task breakdown and implementation.
|
||||
Reference in New Issue
Block a user