CDN - nself-org/plugins GitHub Wiki

CDN Plugin

Field Value
Licence Free (MIT)
Maturity implemented (maturity levels)
Version 1.2.6
Install nself plugin install cdn
Requirements nSelf >=1.0.0

CDN management and integration plugin with multi-provider support, cache purging, HMAC-SHA256 signed URLs, bandwidth analytics, and zone management. Supports Cloudflare, BunnyCDN, Fastly, and Akamai.

Property Value
Port 3036
Category infrastructure
Multi-App source_account_id (UUID)
Min nself 0.4.8

Quick Start

nself plugin run cdn init
nself plugin run cdn server

Configuration

Required Environment Variables

Variable Description
DATABASE_URL PostgreSQL connection string

Optional Environment Variables

Variable Default Description
CDN_PLUGIN_PORT 3036 Server port
CDN_PLUGIN_HOST 0.0.0.0 Server host
CDN_PROVIDER cloudflare Default CDN provider
CDN_CLOUDFLARE_API_TOKEN - Cloudflare API token
CDN_CLOUDFLARE_ZONE_IDS - Comma-separated Cloudflare zone IDs
CDN_BUNNYCDN_API_KEY - BunnyCDN API key
CDN_BUNNYCDN_PULL_ZONE_IDS - Comma-separated BunnyCDN pull zone IDs
CDN_SIGNING_KEY - HMAC-SHA256 key for signed URLs
CDN_SIGNED_URL_TTL 3600 Default signed URL TTL (seconds)
CDN_ANALYTICS_SYNC_INTERVAL 3600000 Analytics sync interval (ms)
CDN_PURGE_BATCH_SIZE 30 Maximum URLs per purge request
CDN_API_KEY - API key for plugin authentication
CDN_RATE_LIMIT_MAX 200 Max requests per window
CDN_RATE_LIMIT_WINDOW_MS 60000 Rate limit window (ms)

CLI Commands

Command Description
init Initialize database schema (4 tables, 3 views)
server Start the HTTP API server
status Show CDN plugin statistics
zones Manage CDN zones (list, create, delete)
purge Purge CDN cache (by URLs, tags, prefixes, or all)
sign Generate signed URLs
analytics View and sync analytics

REST API

Health & Status

Method Path Description
GET /health Health check
GET /ready Readiness check (DB)
GET /live Liveness with memory/uptime

Zones

Method Path Description
POST /api/zones Create zone (body: name, provider, domain, origin_url?, config?, enabled?)
GET /api/zones List zones (query: provider?, limit?, offset?)
GET /api/zones/:id Get zone details

Cache Purging

Method Path Description
POST /api/purge Purge selective cache (body: zone_id, purge_type, urls?, tags?, prefixes?)
POST /api/purge/all Purge entire cache for a zone (body: zone_id, confirm: true)
GET /api/purge/:id Get purge request status

Signed URLs

Method Path Description
POST /api/sign Generate signed URL (body: url, ttl?, ip_restriction?, max_access?, metadata?)
POST /api/sign/batch Generate multiple signed URLs (body: urls[], ttl?)

Analytics

Method Path Description
GET /api/analytics Query analytics (query: zone_id?, start?, end?, limit?)
GET /api/analytics/summary Get analytics summary (query: zone_id?, days?)

Sync & Stats

Method Path Description
POST /sync Trigger analytics sync from provider
GET /api/stats Get plugin statistics

CDN Providers

Provider Features Config Required
cloudflare Purge by URL/tag/prefix/all, analytics, page rules CDN_CLOUDFLARE_API_TOKEN, CDN_CLOUDFLARE_ZONE_IDS
bunnycdn Purge by URL/all, bandwidth analytics, storage zones CDN_BUNNYCDN_API_KEY, CDN_BUNNYCDN_PULL_ZONE_IDS
fastly Purge by URL/surrogate key/all, real-time analytics Provider-specific config in zone config JSONB
akamai Purge by URL/CP code/all, traffic reports Provider-specific config in zone config JSONB

Purge Types

Type Description
urls Purge specific URLs (up to CDN_PURGE_BATCH_SIZE per request)
tags Purge by cache tags / surrogate keys
prefixes Purge by URL prefix (path-based)
all Purge entire zone cache (requires confirm: true)

Signed URLs

Signed URLs use HMAC-SHA256 with the CDN_SIGNING_KEY to generate time-limited, optionally IP-restricted access tokens for CDN resources.

Signature Generation

The signed URL includes query parameters:

  • expires -- Unix timestamp when the URL expires
  • signature -- HMAC-SHA256 hash of the URL path and expiry
  • ip -- (optional) Client IP restriction
  • max -- (optional) Maximum access count

Example Response

{
  "original_url": "https://cdn.example.com/files/report.pdf",
  "signed_url": "https://cdn.example.com/files/report.pdf?expires=1707782400&signature=a1b2c3...",
  "expires_at": "2026-02-12T12:00:00Z",
  "ttl": 3600
}

Batch Signing

Use POST /api/sign/batch to sign multiple URLs in a single request. All URLs share the same TTL and options.

Analytics

The plugin syncs analytics data from CDN providers and stores it locally for querying. Analytics include:

Metric Description
requests Total HTTP requests
bandwidth Total bandwidth (bytes)
visitors Unique visitor count
status_2xx Successful responses
status_3xx Redirects
status_4xx Client errors
status_5xx Server errors
top_paths Most requested paths
top_countries Traffic by country

Analytics Summary

GET /api/analytics/summary returns aggregated metrics over a time period:

{
  "total_requests": 1250000,
  "total_bandwidth": 5368709120,
  "avg_daily_requests": 178571,
  "cache_hit_rate": 94.2,
  "top_paths": [
    { "path": "/images/hero.jpg", "requests": 45000 },
    { "path": "/api/data.json", "requests": 32000 }
  ],
  "top_countries": [
    { "country": "US", "requests": 650000 },
    { "country": "GB", "requests": 180000 }
  ]
}

Database Schema

np_cdn_zones

Column Type Description
id UUID (PK) Zone ID
source_account_id VARCHAR(128) Multi-app isolation
name VARCHAR(255) Zone display name
provider VARCHAR(50) cloudflare, bunnycdn, fastly, akamai
provider_zone_id VARCHAR(255) Provider-specific zone identifier
domain VARCHAR(255) Zone domain
origin_url TEXT Origin server URL
config JSONB Provider-specific configuration
enabled BOOLEAN Whether zone is active
metadata JSONB Arbitrary metadata
created_at TIMESTAMPTZ Creation timestamp
updated_at TIMESTAMPTZ Last update

np_cdn_purge_requests

Column Type Description
id UUID (PK) Purge request ID
source_account_id VARCHAR(128) Multi-app isolation
zone_id UUID (FK) References np_cdn_zones
purge_type VARCHAR(20) urls, tags, prefixes, all
targets TEXT[] URLs, tags, or prefixes to purge
status VARCHAR(20) pending, processing, completed, failed
provider_response JSONB Raw response from CDN provider
error_message TEXT Error details (if failed)
requested_at TIMESTAMPTZ Request timestamp
completed_at TIMESTAMPTZ Completion timestamp
created_at TIMESTAMPTZ Creation timestamp

np_cdn_analytics

Column Type Description
id UUID (PK) Analytics record ID
source_account_id VARCHAR(128) Multi-app isolation
zone_id UUID (FK) References np_cdn_zones
date DATE Analytics date
requests BIGINT Total requests
bandwidth BIGINT Total bandwidth (bytes)
visitors INTEGER Unique visitors
status_2xx INTEGER 2xx responses
status_3xx INTEGER 3xx responses
status_4xx INTEGER 4xx responses
status_5xx INTEGER 5xx responses
cache_hits INTEGER Cache hit count
cache_misses INTEGER Cache miss count
top_paths JSONB Top requested paths
top_countries JSONB Top countries by traffic
metadata JSONB Additional provider-specific metrics
created_at TIMESTAMPTZ Creation timestamp

np_cdn_signed_urls

Column Type Description
id UUID (PK) Record ID
source_account_id VARCHAR(128) Multi-app isolation
original_url TEXT Original unsigned URL
signed_url TEXT Generated signed URL
signature VARCHAR(128) HMAC-SHA256 signature
expires_at TIMESTAMPTZ URL expiration
ip_restriction VARCHAR(45) Optional IP restriction
max_access INTEGER Maximum access count
access_count INTEGER Current access count
metadata JSONB Arbitrary metadata
created_at TIMESTAMPTZ Creation timestamp

Database Views

np_cdn_bandwidth_by_zone

Aggregates total bandwidth per zone with daily breakdown.

np_cdn_cache_hit_rate

Calculates cache hit rate percentage per zone: cache_hits / (cache_hits + cache_misses) * 100.

np_cdn_top_paths

Aggregates most-requested paths across all zones.

Troubleshooting

"CDN provider API key not configured" -- Set the appropriate CDN_CLOUDFLARE_API_TOKEN or CDN_BUNNYCDN_API_KEY for your provider.

Purge request fails -- Verify the zone exists and the provider API key has purge permissions. For Cloudflare, the token needs "Cache Purge" permission. Check CDN_PURGE_BATCH_SIZE if purging many URLs.

Signed URLs rejected -- Verify CDN_SIGNING_KEY is set and matches what the CDN edge is configured to validate. Check that the URL has not expired (expires parameter).

Analytics empty -- Run POST /sync to trigger an analytics sync from the provider. Verify the provider API key has analytics read permissions. Analytics sync runs automatically at CDN_ANALYTICS_SYNC_INTERVAL.

Zone not syncing -- Ensure the zone is enabled: true and the provider_zone_id matches the actual zone ID in the CDN provider dashboard.

nself | nself-plugins | Commands | Issues | Changelog | License

⚠️ **GitHub.com Fallback** ⚠️