eaaa980167
- Add detailed host request configuration guide with examples - Add quick reference guide for common configurations - Include TimeSafari-specific configuration patterns - Add platform-specific configuration examples (Android, iOS, Electron) - Include security, authentication, and observability configurations - Add troubleshooting and debugging guidance - Provide Vue.js integration examples These guides show how the TimeSafari PWA host should configure HTTP requests and network settings for the Daily Notification Plugin.
742 lines
18 KiB
Markdown
742 lines
18 KiB
Markdown
# TimeSafari Daily Notification Plugin - Host Request Configuration Guide
|
|
|
|
**Author**: Matthew Raymer
|
|
**Version**: 1.0.0
|
|
**Created**: 2025-10-08 06:24:57 UTC
|
|
|
|
## Overview
|
|
|
|
This guide explains how the TimeSafari PWA host application should configure HTTP requests and network settings for the Daily Notification Plugin. The plugin uses a **host-managed request pattern** where the host provides network configuration and the plugin handles the actual requests.
|
|
|
|
## Request Configuration Architecture
|
|
|
|
### Plugin Request Pattern
|
|
```
|
|
Host Application (TimeSafari PWA)
|
|
↓ (provides configuration)
|
|
Plugin Network Layer
|
|
↓ (executes requests)
|
|
External APIs (Endorser.ch, etc.)
|
|
```
|
|
|
|
### Key Principles
|
|
1. **Host-Managed Configuration**: Host provides all network settings
|
|
2. **Plugin Execution**: Plugin handles actual HTTP requests
|
|
3. **Structured Logging**: All requests are logged with event IDs
|
|
4. **Circuit Breaker**: Built-in failure handling and retry logic
|
|
5. **ETag Support**: Conditional requests for efficient caching
|
|
|
|
## Host Configuration Options
|
|
|
|
### 1. Basic Network Configuration
|
|
|
|
```typescript
|
|
// In TimeSafari PWA main configuration
|
|
import { DailyNotification } from '@timesafari/daily-notification-plugin';
|
|
|
|
await DailyNotification.configure({
|
|
// Basic network settings
|
|
networkConfig: {
|
|
timeout: 30000, // 30 second timeout
|
|
retryAttempts: 3, // 3 retry attempts
|
|
retryDelay: 1000, // 1 second initial delay
|
|
maxConcurrent: 5, // Max 5 concurrent requests
|
|
userAgent: 'TimeSafari-PWA/1.0.0'
|
|
},
|
|
|
|
// Request headers
|
|
headers: {
|
|
'Accept': 'application/json',
|
|
'Accept-Language': 'en-US,en;q=0.9',
|
|
'Cache-Control': 'no-cache'
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. TimeSafari-Specific Configuration
|
|
|
|
```typescript
|
|
// TimeSafari Endorser.ch API configuration
|
|
await DailyNotification.configure({
|
|
timesafariConfig: {
|
|
// Required: Active DID for authentication
|
|
activeDid: userDid,
|
|
|
|
// API endpoints (optional - defaults provided)
|
|
endpoints: {
|
|
offersToPerson: 'https://endorser.ch/api/v1/offers/person',
|
|
offersToPlans: 'https://endorser.ch/api/v1/offers/plans',
|
|
projectsLastUpdated: 'https://endorser.ch/api/v1/projects/last-updated'
|
|
},
|
|
|
|
// Sync configuration
|
|
syncConfig: {
|
|
enableParallel: true, // Enable parallel API requests
|
|
maxConcurrent: 3, // Max 3 concurrent requests
|
|
batchSize: 10 // Batch size for requests
|
|
},
|
|
|
|
// Credential configuration
|
|
credentialConfig: {
|
|
jwtSecret: process.env.JWT_SECRET,
|
|
tokenExpirationMinutes: 60,
|
|
refreshThresholdMinutes: 10
|
|
},
|
|
|
|
// Error handling policy
|
|
errorPolicy: {
|
|
maxRetries: 3,
|
|
backoffMultiplier: 2,
|
|
activeDidChangeRetries: 5 // Special retry for DID changes
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### 3. Content Fetch Configuration
|
|
|
|
```typescript
|
|
// Configure content fetching
|
|
await DailyNotification.configure({
|
|
contentFetch: {
|
|
enabled: true,
|
|
schedule: '0 8 * * *', // Daily at 8 AM
|
|
|
|
// Request configuration
|
|
url: 'https://endorser.ch/api/v1/community/updates',
|
|
headers: {
|
|
'Authorization': `Bearer ${authToken}`,
|
|
'X-User-DID': userDid,
|
|
'X-Client-Version': '1.0.0'
|
|
},
|
|
timeout: 15000,
|
|
retryAttempts: 2,
|
|
retryDelay: 2000,
|
|
|
|
// Callback configuration
|
|
callbacks: {
|
|
apiService: 'https://api.timesafari.com/notifications/callback',
|
|
database: 'local://notification-storage',
|
|
reporting: 'https://analytics.timesafari.com/events'
|
|
},
|
|
|
|
// Cache policy
|
|
cachePolicy: {
|
|
maxAge: 3600, // 1 hour cache
|
|
staleWhileRevalidate: 1800, // 30 minutes stale
|
|
etagSupport: true
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Platform-Specific Request Configuration
|
|
|
|
### Android Configuration
|
|
|
|
```typescript
|
|
// Android-specific network configuration
|
|
await DailyNotification.configure({
|
|
platform: 'android',
|
|
|
|
// Android network settings
|
|
androidConfig: {
|
|
// WorkManager constraints
|
|
workManagerConstraints: {
|
|
requiresNetworkType: 'CONNECTED',
|
|
requiresBatteryNotLow: false,
|
|
requiresCharging: false,
|
|
requiresDeviceIdle: false,
|
|
requiresStorageNotLow: false
|
|
},
|
|
|
|
// Network security
|
|
networkSecurityConfig: {
|
|
cleartextTrafficPermitted: false,
|
|
certificatePinning: true,
|
|
trustedCertificates: ['endorser.ch', 'api.timesafari.com']
|
|
},
|
|
|
|
// Request configuration
|
|
requestConfig: {
|
|
connectTimeout: 30000,
|
|
readTimeout: 30000,
|
|
writeTimeout: 30000,
|
|
followRedirects: true,
|
|
followSslRedirects: true
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### iOS Configuration
|
|
|
|
```typescript
|
|
// iOS-specific network configuration
|
|
await DailyNotification.configure({
|
|
platform: 'ios',
|
|
|
|
// iOS network settings
|
|
iosConfig: {
|
|
// Background task configuration
|
|
backgroundTasks: {
|
|
'com.timesafari.daily-notification-fetch': {
|
|
identifier: 'com.timesafari.daily-notification-fetch',
|
|
requiresNetworkConnectivity: true,
|
|
requiresExternalPower: false,
|
|
requiresDeviceIdle: false
|
|
}
|
|
},
|
|
|
|
// URL session configuration
|
|
urlSessionConfig: {
|
|
timeoutIntervalForRequest: 30,
|
|
timeoutIntervalForResource: 60,
|
|
allowsCellularAccess: true,
|
|
allowsConstrainedNetworkAccess: true,
|
|
allowsExpensiveNetworkAccess: true
|
|
},
|
|
|
|
// App transport security
|
|
atsConfig: {
|
|
allowsArbitraryLoads: false,
|
|
allowsLocalNetworking: false,
|
|
exceptionDomains: {
|
|
'endorser.ch': {
|
|
nstExceptionAllowsInsecureHTTPLoads: false,
|
|
nstExceptionMinimumTLSVersion: 'TLSv1.2'
|
|
}
|
|
}
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### Electron Configuration
|
|
|
|
```typescript
|
|
// Electron-specific network configuration
|
|
await DailyNotification.configure({
|
|
platform: 'electron',
|
|
|
|
// Electron network settings
|
|
electronConfig: {
|
|
// Session configuration
|
|
sessionConfig: {
|
|
userAgent: 'TimeSafari-Desktop/1.0.0',
|
|
acceptLanguages: ['en-US', 'en'],
|
|
cacheEnabled: true,
|
|
cacheSize: 100 * 1024 * 1024 // 100MB cache
|
|
},
|
|
|
|
// Request configuration
|
|
requestConfig: {
|
|
timeout: 30000,
|
|
maxRedirects: 5,
|
|
followRedirects: true,
|
|
validateSSL: true
|
|
},
|
|
|
|
// Proxy configuration (if needed)
|
|
proxyConfig: {
|
|
enabled: false,
|
|
type: 'http',
|
|
host: '',
|
|
port: 0,
|
|
username: '',
|
|
password: ''
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Advanced Request Configuration
|
|
|
|
### 1. Circuit Breaker Configuration
|
|
|
|
```typescript
|
|
// Circuit breaker for fault tolerance
|
|
await DailyNotification.configure({
|
|
circuitBreaker: {
|
|
failureThreshold: 5, // Open after 5 failures
|
|
recoveryTimeout: 30000, // 30 second recovery timeout
|
|
monitoringPeriod: 60000 // 1 minute monitoring period
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. Rate Limiting Configuration
|
|
|
|
```typescript
|
|
// Rate limiting configuration
|
|
await DailyNotification.configure({
|
|
rateLimiting: {
|
|
maxRequestsPerMinute: 30,
|
|
maxRequestsPerHour: 1000,
|
|
burstLimit: 10,
|
|
backoffStrategy: 'exponential',
|
|
jitterEnabled: true
|
|
}
|
|
});
|
|
```
|
|
|
|
### 3. Authentication Configuration
|
|
|
|
```typescript
|
|
// Authentication configuration
|
|
await DailyNotification.configure({
|
|
authentication: {
|
|
// JWT configuration
|
|
jwt: {
|
|
secret: process.env.JWT_SECRET,
|
|
algorithm: 'HS256',
|
|
expirationMinutes: 60,
|
|
refreshThresholdMinutes: 10
|
|
},
|
|
|
|
// API key configuration
|
|
apiKey: {
|
|
header: 'X-API-Key',
|
|
value: process.env.API_KEY
|
|
},
|
|
|
|
// OAuth configuration
|
|
oauth: {
|
|
clientId: process.env.OAUTH_CLIENT_ID,
|
|
clientSecret: process.env.OAUTH_CLIENT_SECRET,
|
|
tokenEndpoint: 'https://auth.timesafari.com/oauth/token',
|
|
scope: 'notifications:read notifications:write'
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Request Monitoring and Observability
|
|
|
|
### 1. Structured Logging Configuration
|
|
|
|
```typescript
|
|
// Configure structured logging
|
|
await DailyNotification.configure({
|
|
logging: {
|
|
level: 'INFO',
|
|
enableRequestLogging: true,
|
|
enableResponseLogging: true,
|
|
enableErrorLogging: true,
|
|
enablePerformanceLogging: true,
|
|
|
|
// Log formatting
|
|
logFormat: 'json',
|
|
includeHeaders: false, // Don't log sensitive headers
|
|
includeBody: false, // Don't log request/response bodies
|
|
redactSensitiveData: true
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. Metrics Configuration
|
|
|
|
```typescript
|
|
// Configure metrics collection
|
|
await DailyNotification.configure({
|
|
metrics: {
|
|
enabled: true,
|
|
collectionInterval: 60000, // 1 minute
|
|
|
|
// Metrics to collect
|
|
requestMetrics: {
|
|
count: true,
|
|
duration: true,
|
|
statusCodes: true,
|
|
errorRates: true
|
|
},
|
|
|
|
// Performance metrics
|
|
performanceMetrics: {
|
|
cacheHitRate: true,
|
|
networkLatency: true,
|
|
retryCount: true,
|
|
circuitBreakerState: true
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Error Handling Configuration
|
|
|
|
### 1. Retry Configuration
|
|
|
|
```typescript
|
|
// Retry configuration
|
|
await DailyNotification.configure({
|
|
retry: {
|
|
// Exponential backoff
|
|
strategy: 'exponential',
|
|
initialDelay: 1000, // 1 second
|
|
maxDelay: 30000, // 30 seconds
|
|
multiplier: 2,
|
|
jitter: true,
|
|
|
|
// Retry conditions
|
|
retryOn: {
|
|
networkErrors: true,
|
|
timeoutErrors: true,
|
|
serverErrors: true, // 5xx errors
|
|
clientErrors: false // Don't retry 4xx errors
|
|
},
|
|
|
|
// Max retries per request type
|
|
maxRetries: {
|
|
contentFetch: 3,
|
|
notificationDelivery: 2,
|
|
callbackDelivery: 1
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. Fallback Configuration
|
|
|
|
```typescript
|
|
// Fallback configuration
|
|
await DailyNotification.configure({
|
|
fallback: {
|
|
// Content fallbacks
|
|
contentFallbacks: [
|
|
{
|
|
condition: 'network_unavailable',
|
|
action: 'use_cached_content',
|
|
maxAge: 3600 // 1 hour
|
|
},
|
|
{
|
|
condition: 'api_error',
|
|
action: 'use_emergency_content',
|
|
content: {
|
|
title: 'TimeSafari Community Update',
|
|
body: 'Check back later for the latest updates!'
|
|
}
|
|
}
|
|
],
|
|
|
|
// Notification fallbacks
|
|
notificationFallbacks: [
|
|
{
|
|
condition: 'permission_denied',
|
|
action: 'show_in_app_notification'
|
|
},
|
|
{
|
|
condition: 'platform_unsupported',
|
|
action: 'log_warning'
|
|
}
|
|
]
|
|
}
|
|
});
|
|
```
|
|
|
|
## Security Configuration
|
|
|
|
### 1. SSL/TLS Configuration
|
|
|
|
```typescript
|
|
// SSL/TLS configuration
|
|
await DailyNotification.configure({
|
|
security: {
|
|
// Certificate pinning
|
|
certificatePinning: {
|
|
enabled: true,
|
|
pins: [
|
|
{
|
|
hostname: 'endorser.ch',
|
|
pins: [
|
|
'sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=',
|
|
'sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB='
|
|
]
|
|
}
|
|
]
|
|
},
|
|
|
|
// TLS configuration
|
|
tls: {
|
|
minVersion: '1.2',
|
|
maxVersion: '1.3',
|
|
cipherSuites: [
|
|
'TLS_AES_256_GCM_SHA384',
|
|
'TLS_CHACHA20_POLY1305_SHA256',
|
|
'TLS_AES_128_GCM_SHA256'
|
|
]
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. Data Protection Configuration
|
|
|
|
```typescript
|
|
// Data protection configuration
|
|
await DailyNotification.configure({
|
|
dataProtection: {
|
|
// Encryption at rest
|
|
encryption: {
|
|
enabled: true,
|
|
algorithm: 'AES-256-GCM',
|
|
keyDerivation: 'PBKDF2'
|
|
},
|
|
|
|
// Data redaction
|
|
redaction: {
|
|
enabled: true,
|
|
patterns: [
|
|
'password',
|
|
'token',
|
|
'secret',
|
|
'key',
|
|
'authorization'
|
|
]
|
|
},
|
|
|
|
// Data retention
|
|
retention: {
|
|
maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
|
|
autoCleanup: true
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Integration Examples
|
|
|
|
### 1. TimeSafari PWA Integration
|
|
|
|
```typescript
|
|
// In TimeSafari PWA main.ts
|
|
import { DailyNotification } from '@timesafari/daily-notification-plugin';
|
|
import { TimeSafariIntegrationService } from '@timesafari/daily-notification-plugin';
|
|
|
|
// Initialize with TimeSafari configuration
|
|
const initializeDailyNotifications = async () => {
|
|
try {
|
|
// Configure plugin with TimeSafari settings
|
|
await DailyNotification.configure({
|
|
// Basic configuration
|
|
storage: 'tiered',
|
|
ttlSeconds: 1800,
|
|
enableETagSupport: true,
|
|
|
|
// TimeSafari-specific configuration
|
|
timesafariConfig: {
|
|
activeDid: userDid,
|
|
endpoints: {
|
|
offersToPerson: 'https://endorser.ch/api/v1/offers/person',
|
|
offersToPlans: 'https://endorser.ch/api/v1/offers/plans'
|
|
},
|
|
syncConfig: {
|
|
enableParallel: true,
|
|
maxConcurrent: 3,
|
|
batchSize: 10
|
|
}
|
|
},
|
|
|
|
// Network configuration
|
|
networkConfig: {
|
|
timeout: 30000,
|
|
retryAttempts: 3,
|
|
retryDelay: 1000,
|
|
maxConcurrent: 5
|
|
},
|
|
|
|
// Authentication
|
|
authentication: {
|
|
jwt: {
|
|
secret: process.env.JWT_SECRET,
|
|
algorithm: 'HS256',
|
|
expirationMinutes: 60
|
|
}
|
|
},
|
|
|
|
// Observability
|
|
logging: {
|
|
level: 'INFO',
|
|
enableRequestLogging: true,
|
|
redactSensitiveData: true
|
|
},
|
|
|
|
// Security
|
|
security: {
|
|
certificatePinning: {
|
|
enabled: true,
|
|
pins: [
|
|
{
|
|
hostname: 'endorser.ch',
|
|
pins: ['sha256/...']
|
|
}
|
|
]
|
|
}
|
|
}
|
|
});
|
|
|
|
// Initialize TimeSafari integration
|
|
const integrationService = TimeSafariIntegrationService.getInstance();
|
|
await integrationService.initialize({
|
|
activeDid: userDid,
|
|
storageAdapter: timeSafariStorageAdapter,
|
|
endorserApiBaseUrl: 'https://endorser.ch/api/v1'
|
|
});
|
|
|
|
console.log('Daily notifications configured successfully');
|
|
|
|
} catch (error) {
|
|
console.error('Failed to configure daily notifications:', error);
|
|
}
|
|
};
|
|
|
|
// Initialize on app startup
|
|
initializeDailyNotifications();
|
|
```
|
|
|
|
### 2. Vue.js Component Integration
|
|
|
|
```typescript
|
|
// In TimeSafari PWA Vue component
|
|
import { defineComponent } from 'vue';
|
|
import { DailyNotification } from '@timesafari/daily-notification-plugin';
|
|
|
|
export default defineComponent({
|
|
name: 'DailyNotificationSettings',
|
|
|
|
async mounted() {
|
|
// Configure notifications for this component
|
|
await DailyNotification.configure({
|
|
// Component-specific configuration
|
|
contentFetch: {
|
|
enabled: true,
|
|
schedule: '0 9 * * *', // 9 AM daily
|
|
url: 'https://endorser.ch/api/v1/community/updates',
|
|
headers: {
|
|
'Authorization': `Bearer ${this.authToken}`,
|
|
'X-User-DID': this.userDid
|
|
},
|
|
callbacks: {
|
|
onSuccess: async (data) => {
|
|
// Handle successful fetch
|
|
this.updateNotificationContent(data);
|
|
},
|
|
onError: async (error) => {
|
|
// Handle fetch error
|
|
this.handleNotificationError(error);
|
|
}
|
|
}
|
|
}
|
|
});
|
|
},
|
|
|
|
methods: {
|
|
async updateNotificationContent(data: Record<string, unknown>) {
|
|
// Update UI with new content
|
|
this.notificationData = data;
|
|
},
|
|
|
|
async handleNotificationError(error: Error) {
|
|
// Handle error in UI
|
|
this.showError(error.message);
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Configuration Issues
|
|
|
|
#### 1. Network Timeout Issues
|
|
```typescript
|
|
// Increase timeout for slow networks
|
|
await DailyNotification.configure({
|
|
networkConfig: {
|
|
timeout: 60000, // 60 seconds
|
|
retryAttempts: 5,
|
|
retryDelay: 2000
|
|
}
|
|
});
|
|
```
|
|
|
|
#### 2. Authentication Issues
|
|
```typescript
|
|
// Debug authentication
|
|
await DailyNotification.configure({
|
|
logging: {
|
|
level: 'DEBUG',
|
|
enableRequestLogging: true,
|
|
includeHeaders: true // Temporarily enable for debugging
|
|
}
|
|
});
|
|
```
|
|
|
|
#### 3. Certificate Issues
|
|
```typescript
|
|
// Disable certificate pinning for development
|
|
await DailyNotification.configure({
|
|
security: {
|
|
certificatePinning: {
|
|
enabled: false // Only for development
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### Debugging Request Issues
|
|
|
|
#### 1. Enable Debug Logging
|
|
```typescript
|
|
// Enable comprehensive logging
|
|
await DailyNotification.configure({
|
|
logging: {
|
|
level: 'DEBUG',
|
|
enableRequestLogging: true,
|
|
enableResponseLogging: true,
|
|
enableErrorLogging: true,
|
|
enablePerformanceLogging: true
|
|
}
|
|
});
|
|
```
|
|
|
|
#### 2. Monitor Request Metrics
|
|
```typescript
|
|
// Get request statistics
|
|
const stats = await DailyNotification.getRequestStats();
|
|
console.log('Request Statistics:', stats);
|
|
|
|
// Get error statistics
|
|
const errors = await DailyNotification.getErrorStats();
|
|
console.log('Error Statistics:', errors);
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Configuration Management
|
|
- **Environment Variables**: Use environment variables for sensitive data
|
|
- **Configuration Validation**: Validate configuration on startup
|
|
- **Graceful Degradation**: Provide fallbacks for missing configuration
|
|
- **Configuration Updates**: Support runtime configuration updates
|
|
|
|
### 2. Security Best Practices
|
|
- **Certificate Pinning**: Enable for production environments
|
|
- **Data Redaction**: Always redact sensitive data in logs
|
|
- **Token Management**: Use secure token storage and rotation
|
|
- **Network Security**: Use HTTPS for all requests
|
|
|
|
### 3. Performance Best Practices
|
|
- **Connection Pooling**: Reuse HTTP connections
|
|
- **Request Batching**: Batch multiple requests when possible
|
|
- **Caching**: Use ETag support for efficient caching
|
|
- **Rate Limiting**: Implement appropriate rate limits
|
|
|
|
### 4. Monitoring Best Practices
|
|
- **Structured Logging**: Use structured logs with event IDs
|
|
- **Metrics Collection**: Collect relevant performance metrics
|
|
- **Error Tracking**: Track and analyze error patterns
|
|
- **Health Checks**: Implement health check endpoints
|
|
|
|
---
|
|
|
|
**Note**: This configuration guide should be updated as the plugin evolves. Regular review and updates are recommended to ensure accuracy and completeness.
|