121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# DCRouter Storage Overview
|
|
|
|
DCRouter uses two complementary storage systems: **StorageManager** for configuration and state, and **CacheDb** for time-limited cached data.
|
|
|
|
## StorageManager (Key-Value Store)
|
|
|
|
A lightweight, pluggable key-value store for configuration, credentials, and runtime state. Data is persisted as flat JSON files on disk by default.
|
|
|
|
### Default Path
|
|
|
|
```
|
|
~/.serve.zone/dcrouter/storage/
|
|
```
|
|
|
|
Configurable via `options.storage.fsPath` or `options.baseDir`.
|
|
|
|
### Backends
|
|
|
|
```typescript
|
|
// Filesystem (default)
|
|
storage: { fsPath: '/var/lib/dcrouter/data' }
|
|
|
|
// Custom (Redis, S3, etc.)
|
|
storage: {
|
|
readFunction: async (key) => await redis.get(key),
|
|
writeFunction: async (key, value) => await redis.set(key, value),
|
|
}
|
|
|
|
// In-memory (omit storage config — data lost on restart)
|
|
```
|
|
|
|
### What's Stored
|
|
|
|
| Prefix | Contents | Managed By |
|
|
|--------|----------|------------|
|
|
| `/vpn/server-keys` | VPN server Noise + WireGuard keypairs | `VpnManager` |
|
|
| `/vpn/clients/{clientId}` | VPN client registrations (keys, tags, description, assigned IP) | `VpnManager` |
|
|
| `/config-api/routes/{uuid}.json` | Programmatic routes (created via OpsServer API) | `RouteConfigManager` |
|
|
| `/config-api/tokens/{uuid}.json` | API tokens (hashed secrets, scopes, expiry) | `ApiTokenManager` |
|
|
| `/config-api/overrides/{routeName}.json` | Hardcoded route overrides (enable/disable) | `RouteConfigManager` |
|
|
| `/email/bounces/suppression-list.json` | Email bounce suppression list | `smartmta` |
|
|
| `/certs/*` | TLS certificates and ACME state | `SmartAcme` (via `StorageBackedCertManager`) |
|
|
|
|
### API
|
|
|
|
```typescript
|
|
// Read/write JSON
|
|
await storageManager.getJSON<T>(key);
|
|
await storageManager.setJSON(key, value);
|
|
|
|
// Raw string read/write
|
|
await storageManager.get(key);
|
|
await storageManager.set(key, value);
|
|
|
|
// List keys by prefix
|
|
await storageManager.list('/vpn/clients/');
|
|
|
|
// Delete
|
|
await storageManager.delete(key);
|
|
```
|
|
|
|
## CacheDb (Embedded MongoDB)
|
|
|
|
An embedded MongoDB-compatible database (via `@push.rocks/smartdb` + `@push.rocks/smartdata`) for cached data with automatic TTL-based cleanup.
|
|
|
|
### Default Path
|
|
|
|
```
|
|
~/.serve.zone/dcrouter/tsmdb/
|
|
```
|
|
|
|
Configurable via `options.cacheConfig.storagePath`.
|
|
|
|
### What's Cached
|
|
|
|
| Document Type | Default TTL | Purpose |
|
|
|--------------|-------------|---------|
|
|
| `CachedEmail` | 30 days | Email metadata cache for dashboard display |
|
|
| `CachedIPReputation` | 1 day | IP reputation lookup results (DNSBL checks) |
|
|
|
|
### Configuration
|
|
|
|
```typescript
|
|
cacheConfig: {
|
|
enabled: true, // default: true
|
|
storagePath: '~/.serve.zone/dcrouter/tsmdb', // default
|
|
dbName: 'dcrouter', // default
|
|
cleanupIntervalHours: 1, // how often to purge expired records
|
|
ttlConfig: {
|
|
emails: 30, // days
|
|
ipReputation: 1, // days
|
|
bounces: 30, // days (reserved)
|
|
dkimKeys: 90, // days (reserved)
|
|
suppression: 30, // days (reserved)
|
|
},
|
|
}
|
|
```
|
|
|
|
### How It Works
|
|
|
|
1. `CacheDb` starts a `LocalSmartDb` instance (embedded MongoDB process)
|
|
2. `smartdata` connects to it via Unix socket
|
|
3. Document classes (`CachedEmail`, `CachedIPReputation`) are decorated with `@Collection` and use `smartdata` ORM
|
|
4. `CacheCleaner` runs on a timer, purging records older than their configured TTL
|
|
|
|
### Disabling
|
|
|
|
For development or lightweight deployments, disable the cache to avoid starting a MongoDB process:
|
|
|
|
```typescript
|
|
cacheConfig: { enabled: false }
|
|
```
|
|
|
|
## When to Use Which
|
|
|
|
| Use Case | System | Why |
|
|
|----------|--------|-----|
|
|
| VPN keys, API tokens, routes, certs | **StorageManager** | Small JSON blobs, key-value access, no queries needed |
|
|
| Email metadata, IP reputation | **CacheDb** | Time-series data, TTL expiry, potential for queries/aggregation |
|
|
| Runtime state (connected clients, metrics) | **Neither** | In-memory only, rebuilt on startup |
|