Development rules for a tunnel-server TypeScript project that enables communication between mobile devices and laptops without requiring a public IP address.
You are working on the **tunnel-server** - a proxy server that enables communication between mobile devices (iPhone) and the laptop app without requiring a public IP address.
The tunnel server is a **thin proxy layer** with the following responsibilities:
All code MUST follow these principles:
Example:
```typescript
// ✅ Good
function handleRequest(req: TunnelRequest): Promise<TunnelResponse> {
// Implementation
}
// ❌ Bad
function handleRequest(req: any) {
// Implementation
}
```
All errors must be handled gracefully:
Example:
```typescript
class TunnelServer {
async handleWebSocketConnection(ws: WebSocket, apiKey: string): Promise<void> {
try {
const tunnel = await this.validateTunnel(apiKey);
this.logger.info('Tunnel connected', {
tunnelId: tunnel.id,
timestamp: Date.now(),
});
ws.on('close', () => {
this.logger.info('Tunnel disconnected', { tunnelId: tunnel.id });
this.removeTunnel(tunnel.id);
});
this.registerTunnel(tunnel.id, ws);
} catch (error) {
this.logger.error('Tunnel connection failed', { error, apiKey: '***' });
ws.close(1008, 'Authentication failed');
}
}
}
```
Use structured logging throughout:
1. **WebSocket connection**: Laptop connects via WebSocket with API key
2. **HTTP proxy**: Mobile devices send HTTP requests, tunnel forwards to laptop
3. **Request routing**: Route `/api/{tunnel_id}/*` to connected laptop
4. **Bidirectional**: Support both HTTP → laptop and laptop → mobile
```typescript
// ❌ No error handling
ws.on('message', (data) => {
forwardToLaptop(data); // What if this fails?
});
// ❌ Logging secrets
logger.info('Tunnel connected', { apiKey }); // ❌ Never do this
// ❌ Using any
function handleRequest(req: any): void {
// No type safety
}
```
This package is published to GitHub Packages and MUST have:
Create `.github/workflows/publish-tunnel-server.yml`:
1. **Security audit**: `npm audit --audit-level=moderate` (MANDATORY before build)
2. **Tests**: `npm test` (MANDATORY, all must pass before build)
3. **Type check**: `npm run type-check`
4. **Build**: `npm run build`
5. **Publish**: Publish to GitHub Packages
Ensure `package.json` includes:
When making changes:
1. **Review architecture**: Keep tunnel server as a thin proxy
2. **Handle errors**: Add proper error handling for connection issues
3. **Add logging**: Log important events (connections, disconnections, errors)
4. **Maintain type safety**: No `any` types, use explicit return types
5. **Test**: Test WebSocket connections and HTTP proxying
6. **Security**: Validate inputs, never log secrets
7. **CI/CD**: Ensure GitHub Actions workflow includes audit + tests before publishing
The tunnel server must remain a simple, secure, and reliable proxy layer. Focus on connection management, error handling, structured logging, and type safety. Never add business logic - keep it in the laptop app.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/tunnel-server-typescript-development/raw