## DescriptionBrief description of what this PR does and why.## Changes- Bullet list of key changes- Include both code and configuration changes## TestingHow to test these changes:1. Step-by-step testing instructions2. Expected behavior## Breaking Changes- List any breaking changes- Include migration guide if applicable## Related IssuesFixes #123
// ✅ Good: Explain WHY, not WHAT// Cloudflare requires lowercase DNS labelsconst normalizedSlug = slug.toLowerCase();// ✅ Good: Document non-obvious behavior// Heartbeat must arrive within LEASE_TIMEOUT_SEC or tunnel is reapedawait sendHeartbeat();// ❌ Avoid: Obvious comments// Set the port to 8080const port = 8080;// ❌ Avoid: Commented-out code// const oldImplementation = () => { ... };
Keep comments concise and update them when code changes.
// ✅ Use descriptive error messagesif (!slug.match(/^[a-z0-9-]+$/)) { throw new Error( `Invalid slug "${slug}". ` + 'Only lowercase letters, numbers, and hyphens are allowed.' );}// ✅ Catch and handle specific errorstry { await createCloudfareTunnel(slug);} catch (error) { if (error.statusCode === 409) { throw new Error(`Tunnel "${slug}" already exists`); } throw error;}// ❌ Avoid swallowing errorstry { await riskyOperation();} catch { // Silent failure - debugging nightmare!}
// ✅ Use async/await for clarityasync function createTunnel(slug: string): Promise<Tunnel> { const tunnel = await cloudflare.createTunnel(slug); const dns = await cloudflare.createDnsRecord(slug); return { tunnel, dns };}// ✅ Handle errors properlyasync function stopTunnel(id: string): Promise<void> { try { await cloudflare.deleteTunnel(id); } catch (error) { logger.error('Failed to delete tunnel', { id, error }); throw error; }}// ❌ Don't mix promises and callbacksfunction badExample(slug: string) { return new Promise((resolve, reject) => { createTunnel(slug).then(resolve).catch(reject); });}
# Update version in package.json filespnpm --filter @ripeseed/shared version patchpnpm --filter @ripeseed/rs-tunnel version patch# Commit version bumpsgit add .git commit -m "chore: bump version to 0.1.3"# Create and push taggit tag v0.1.3git push origin main --tags
When contributing, respect these core product rules:
Email Domain Enforcement
Only emails ending in ALLOWED_EMAIL_DOMAIN are allowed.
// API must validate email domainif (!email.endsWith(process.env.ALLOWED_EMAIL_DOMAIN)) { throw new Error('Unauthorized email domain');}
Slack Workspace Check
Slack workspace must match ALLOWED_SLACK_TEAM_ID.
// API must verify Slack team ID during OAuthif (slackTeamId !== process.env.ALLOWED_SLACK_TEAM_ID) { throw new Error('Unauthorized Slack workspace');}
Single-Label Slugs Only
No nested domains allowed. Slugs must be single-label DNS labels.
Maximum 5 active tunnels per user (server-side enforcement).
// API must enforce quota before creating tunnelconst activeCount = await db.countActiveTunnels(userId);if (activeCount >= MAX_ACTIVE_TUNNELS) { throw new Error('Maximum active tunnels reached');}
DNS Cleanup on Stop
DNS records must be deleted when tunnel stops.
// On tunnel stop, cleanup MUST include DNSasync function stopTunnel(tunnelId: string) { await cloudflare.deleteDnsRecord(tunnelId); await cloudflare.deleteTunnel(tunnelId); await db.markTunnelStopped(tunnelId);}
Stale Lease Cleanup
If client dies, cleanup worker must remove tunnel + DNS.
// Reaper runs periodically and cleans stale leasesconst staleLeases = await db.findStaleTunnels( Date.now() - LEASE_TIMEOUT_SEC * 1000);for (const tunnel of staleLeases) { await cleanupTunnel(tunnel.id);}
No Provider Credentials in CLI
CLI must never hold Cloudflare API credentials.
// ✅ CLI receives tunnel-specific token from APIconst { tunnelToken } = await api.createTunnel({ slug, port });await runCloudflared(tunnelToken);// ❌ CLI should never have CLOUDFLARE_API_TOKENconst cloudflare = new CloudflareClient(process.env.CLOUDFLARE_API_TOKEN);
