google-drive-content-adapter/specs/001-gdrive-url-header/research.md

# Research: Google Drive Original URL Header

**Feature**: 001-gdrive-url-header  
**Date**: 2026-03-27  
**Status**: Complete

## Purpose

Research implementation approach for adding `X-Verint-KAB-Original-URL` HTTP response header containing the original Google Drive URL for exported documents.

## Research Questions

1. What is the correct Google Drive URL format for linking to files?
2. How and where is the document/file ID available in the current codebase?
3. What is the existing pattern for setting HTTP response headers?
4. Where in the export response flow should the header be added?
5. How should errors be handled when the file ID is unavailable?

---

## 1. Google Drive URL Format

### Decision: Use `https://drive.google.com/file/d/{fileId}` format

**Rationale:**
- This is the standard user-facing URL format for Google Drive files
- Matches the format specified in spec.md (FR-003)
- Alternative format `https://drive.google.com/open?id={fileId}` is also valid but the `/file/d/` format is more modern

**Current Codebase Context:**
- The codebase currently uses Google Drive API URLs (e.g., `https://www.googleapis.com/drive/v3/files`)
- These are API endpoints, not user-facing URLs
- User-facing URLs are not currently constructed anywhere in the codebase

**Implementation:**
```javascript
const driveUrl = `https://drive.google.com/file/d/${document.id}`;
res.setHeader("X-Verint-KAB-Original-URL", driveUrl);
```

**Alternatives Considered:**
- `https://drive.google.com/open?id={fileId}` - Older format, less readable
- `https://docs.google.com/document/d/{fileId}` - Document-specific, not suitable for all file types

---

## 2. Document ID Availability

### Decision: Use `document.id` after metadata fetch (after proxy.js line 278)

**Rationale:**
- The document ID flows through multiple stages in the request lifecycle
- Using `document.id` (from Google Drive API response) ensures the ID is validated
- More reliable than the `documentId` route parameter which could be malformed

**ID Flow Through System:**

1. **Route Parsing** (`googleDriveAdapterHelper.js:466-470`):
   - URL pattern: `/documents/{documentId}`
   - Extracted as `routeResult.documentId`

2. **Request Handler** (`proxy.js:467`):
   - Passed to `handleDocumentExportRequest(res, routeResult.documentId, requestId)`

3. **Export Handler** (`proxy.js:255`):
   - Available as `documentId` parameter throughout function
   - Metadata fetched at line 260-278
   - After line 278: `document.id` contains validated ID from Google Drive

**Code Location:**
```javascript
// proxy.js:260-278
const metadataUrl = `https://www.googleapis.com/drive/v3/files/${documentId}`;
const metadataResponse = await axios.get(metadataUrl, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const document = metadataResponse.data;
// document.id is now available and validated
```

**Alternatives Considered:**
- Using `documentId` parameter directly - Less reliable as it hasn't been validated by Google Drive
- Extracting from API response URL - Unnecessary complexity

---

## 3. HTTP Response Header Pattern

### Decision: Follow existing `res.setHeader(name, value)` pattern

**Rationale:**
- Consistent with all existing header setting in the codebase
- Standard Node.js HTTP response API
- Custom headers already use `X-` prefix convention

**Current Header Setting Patterns:**

**Export Success Path** (`proxy.js:374-386`):
```javascript
res.setHeader("Content-Type", contentType);
res.setHeader("X-Request-Id", requestId);
res.setHeader("Content-Disposition", contentDisposition);
if (contentLength) {
  res.setHeader("Content-Length", contentLength);
}
```

**Sitemap Handler** (`proxy.js:224-226`):
```javascript
res.setHeader("Content-Type", "application/xml; charset=utf-8");
res.setHeader("X-Request-Id", requestId);
res.setHeader("X-Document-Count", documents.length.toString());
```

**Error Paths** (lines 302, 338, 362, 415):
```javascript
res.setHeader("X-Request-Id", requestId);
```

**Pattern Consistency:**
- All custom headers use `X-` prefix
- Headers are set immediately before response streaming or `res.end()`
- `X-Request-Id` is always present for traceability

**Alternatives Considered:**
- Using helper function to set headers - Unnecessary for simple operation
- Setting headers in helper module - Violates monolithic architecture

---

## 4. Export Response Flow

### Decision: Add header at line 377 or 383 in `handleDocumentExportRequest()`

**Rationale:**
- Single code location handles all successful export responses
- All export formats (PDF, DOCX, text) flow through this path
- Headers must be set before streaming starts (line 389)
- `document.id` is guaranteed to be available at this point

**Exact Code Location** (`proxy.js:374-389`):
```javascript
// Step 5: Set response headers
res.statusCode = 200;
res.setHeader("Content-Type", contentType);
res.setHeader("X-Request-Id", requestId);

// Generate Content-Disposition header
const sanitizedFilename = googleDriveAdapterHelper.sanitizeFilename(document.name);
const contentDisposition = `inline; filename="${sanitizedFilename}.${fileExtension}"`;
res.setHeader("Content-Disposition", contentDisposition);

// *** ADD NEW HEADER HERE (after line 377 or 382) ***
res.setHeader("X-Verint-KAB-Original-URL", `https://drive.google.com/file/d/${document.id}`);

if (contentLength) {
  res.setHeader("Content-Length", contentLength);
}

// Step 6: Stream the content
contentResponse.data.pipe(res);
```

**Why This Location:**
- ✅ Success path only (200 OK responses)
- ✅ After `document.id` is validated (line 278)
- ✅ Before content streaming begins (line 389)
- ✅ Alongside other response headers
- ✅ All export formats use this code path

**Alternatives Considered:**
- Setting header after metadata fetch (line 278) - Too early, may fail before export
- Setting in helper function - Violates monolithic architecture
- Setting in multiple locations - Error-prone, inconsistent

---

## 5. Error Handling

### Decision: Omit header on error responses (recommended)

**Rationale:**
- Simpler implementation and clearer API contract
- Clients can check for header presence to determine success
- Avoids confusion between empty string and missing value
- Aligns with existing pattern (custom headers only on success paths)

**Error Scenarios:**

| Scenario | Error Code | File ID Available? | Current Headers | Recommendation |
|----------|-----------|-------------------|-----------------|----------------|
| Invalid document ID format | 404 | No (route param) | X-Request-Id only | Omit URL header |
| Document not found (404 from Drive) | 404 | No (validation failed) | X-Request-Id only | Omit URL header |
| Unsupported mimetype | 403 | Yes (after metadata) | X-Request-Id only | Omit URL header |
| Size limit exceeded | 413 | Yes (after metadata) | X-Request-Id only | Omit URL header |
| Stream error | 500 | Yes (during transfer) | Already sent | Cannot add header |
| General API error | 500 | No | X-Request-Id only | Omit URL header |

**FR-006 Interpretation:**
- Spec states: "empty or null value when document ID cannot be determined"
- HTTP headers cannot have null values (only strings)
- **Interpretation:** Omit header entirely on error paths (cleaner than empty string)

**Implementation:**
- **Success path (200 OK):** Include header with valid URL
- **Error paths (4xx, 5xx):** Do not include header
- No changes needed to existing error handlers

**Alternatives Considered:**
- Setting empty string `""` on errors - Ambiguous, adds no value
- Setting placeholder URL - Misleading, could cause client errors
- Setting header with error indicator - Violates HTTP semantics

---

## Technology Stack Decisions

### No New Dependencies Required

**Decision: Use standard JavaScript string operations**

**Rationale:**
- URL construction is simple: `https://drive.google.com/file/d/${document.id}`
- No URL encoding needed (file IDs are alphanumeric)
- No validation library needed (Google Drive API validates IDs)
- Aligns with constitution's preference for Node.js built-ins

**Dependencies Analysis:**
- ✅ No new npm packages required
- ✅ Uses existing `res.setHeader()` Node.js API
- ✅ Simple string interpolation (ES6 template literals)

---

## Best Practices

### URL Construction
- Use `document.id` (validated by Google Drive) not `documentId` (route parameter)
- Use template literal for clarity: `` `https://drive.google.com/file/d/${document.id}` ``
- No need for helper function (one-line operation)

### Header Naming
- Use `X-Verint-KAB-Original-URL` exactly as specified in FR-001
- Note: `X-` prefix is deprecated in RFC 6648 but required by client standards (per spec assumptions)

### Testing Strategy
- Contract tests: Verify header presence and format in successful exports
- Integration tests: Verify header contains correct file ID for real Drive documents
- Unit tests: Not needed (too simple to warrant isolated testing)
- Coverage: Test all export formats (PDF, DOCX, plain text)

### Performance
- String concatenation overhead: < 1ms
- Memory impact: ~100 bytes per response
- Well within SC-005 requirement (< 5ms overhead)

---

## Implementation Checklist

- [ ] Add header at line 377-383 in `handleDocumentExportRequest()`
- [ ] Use `document.id` for URL construction
- [ ] Use format: `https://drive.google.com/file/d/${document.id}`
- [ ] Omit header on error responses (no changes to error handlers)
- [ ] Write contract tests for header presence and format
- [ ] Write integration tests with real Drive API responses
- [ ] Test all export formats (PDF, DOCX, plain text)
- [ ] Verify performance impact < 5ms
- [ ] Update API documentation (contracts/response-headers.md)

---

## References

- **Spec**: `/specs/001-gdrive-url-header/spec.md`
- **Constitution**: `.specify/memory/constitution.md`
- **Code**: `src/proxyScripts/proxy.js` (lines 255-425)
- **Helpers**: `src/globalVariables/googleDriveAdapterHelper.js`
- **Google Drive URLs**: https://developers.google.com/drive/api/guides/manage-sharing