@robiki/proxy 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robiki/proxy",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A flexible HTTP/2 proxy server with WebSocket support, configurable routing, CORS, and validation. Use as npm package or Docker container.",
   "keywords": [
     "proxy",
@@ -60,7 +60,11 @@
     "test:docker": "make test-docker-full",
     "test:docker:config": "make test-docker-config",
     "test:all": "yarn test && yarn test:docker",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "yarn build",
+    "publish:npm": "npm publish",
+    "publish:docker": "make docker-push-hub",
+    "publish:docker:multiarch": "make docker-push-multiarch",
+    "publish:all": "yarn publish:npm && yarn publish:docker"
   },
   "devDependencies": {
     "@types/node": "25.0.3",
@@ -83,4 +87,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/tests/README.md

@@ -0,0 +1,293 @@
+# Robiki Proxy Tests
+
+This directory contains comprehensive tests for the Robiki Proxy library.
+
+## Test Structure
+
+```
+tests/
+├── unit/                    # Unit tests for individual components
+│   └── utils/              # Utility function tests
+│       ├── config.test.ts  # Configuration management tests
+│       ├── server.test.ts  # Server utility tests
+│       ├── files.test.ts   # File utility tests
+│       ├── time.test.ts    # Time utility tests
+│       └── uuid.test.ts    # UUID generation tests
+├── integration/            # Integration tests
+│   ├── proxy-server.test.ts    # ProxyServer class tests
+│   ├── http-proxy.test.ts      # HTTP proxy handler tests
+│   ├── full-proxy.test.ts      # Full proxy integration tests
+│   └── config-loading.test.ts  # Configuration file loading tests
+├── advanced/               # Advanced feature tests
+│   ├── websocket.test.ts   # WebSocket proxying tests
+│   └── http2.test.ts       # HTTP/2 specific tests
+├── docker/                 # Docker integration tests
+│   ├── test-docker.sh      # Full Docker integration test
+│   ├── test-config-loading.sh  # Config loading test
+│   ├── validate.sh         # Prerequisites validation
+│   └── README.md           # Docker testing documentation
+└── helpers/                # Shared test utilities
+    └── test-utils.ts       # Reusable test helpers
+```
+
+## Running Tests
+
+### Run all tests
+
+```bash
+yarn test
+```
+
+### Run tests in watch mode
+
+```bash
+yarn test:watch
+```
+
+### Run tests with UI
+
+```bash
+yarn test:ui
+```
+
+### Run tests with coverage
+
+```bash
+yarn test:coverage
+```
+
+### Run Docker tests
+
+```bash
+# Full Docker integration test
+yarn test:docker
+
+# Config loading test
+yarn test:docker:config
+
+# Run all tests (unit + integration + Docker)
+yarn test:all
+```
+
+### Run specific test file
+
+```bash
+yarn test tests/unit/utils/config.test.ts
+```
+
+### Run tests matching a pattern
+
+```bash
+yarn test -t "ProxyConfig"
+```
+
+## Test Categories
+
+### Unit Tests
+
+Unit tests focus on testing individual functions and classes in isolation. They are fast and don't require external dependencies.
+
+**Coverage includes:**
+
+- Configuration loading and management
+- CORS header generation
+- Header conversion (HTTP/1.1 ↔ HTTP/2)
+- Time utilities
+- File type detection
+- UUID generation
+
+### Integration Tests
+
+Integration tests verify that different components work together correctly. They may start actual servers and make real HTTP requests.
+
+**Coverage includes:**
+
+- ProxyServer class functionality
+- HTTP request proxying
+- Route resolution
+- URL remapping
+- Request validation
+- Multi-backend routing
+- Configuration file loading (proxy.config.json)
+- Environment variable configuration
+
+### Advanced Tests
+
+Advanced tests cover complex scenarios and protocol-specific features.
+
+**Coverage includes:**
+
+- WebSocket connection proxying
+- WebSocket message forwarding
+- WebSocket validation
+- HTTP/2 stream handling
+- HTTP/2 multiplexing
+- HTTP/2 header compression concepts
+
+### Docker Tests
+
+Docker tests verify the containerized deployment of the proxy server.
+
+**Coverage includes:**
+
+- Docker image build process
+- Container startup and health
+- Configuration file mounting and loading
+- Port accessibility
+- Environment variable handling
+- Graceful shutdown
+- Docker Compose integration
+
+See [tests/docker/README.md](docker/README.md) for detailed Docker testing documentation.
+
+## Writing Tests
+
+### Test Structure
+
+Tests follow the Arrange-Act-Assert pattern:
+
+```typescript
+it('should do something', () => {
+  // Arrange: Set up test data
+  const config = { ... };
+
+  // Act: Execute the code being tested
+  const result = someFunction(config);
+
+  // Assert: Verify the results
+  expect(result).toBe(expectedValue);
+});
+```
+
+### Async Tests
+
+For asynchronous operations, use async/await:
+
+```typescript
+it('should handle async operations', async () => {
+  const result = await asyncFunction();
+  expect(result).toBeDefined();
+});
+```
+
+### Test Lifecycle Hooks
+
+Use lifecycle hooks to set up and tear down test environments:
+
+```typescript
+describe('Test Suite', () => {
+  beforeAll(async () => {
+    // Runs once before all tests
+  });
+
+  afterAll(async () => {
+    // Runs once after all tests
+  });
+
+  beforeEach(() => {
+    // Runs before each test
+  });
+
+  afterEach(() => {
+    // Runs after each test
+  });
+});
+```
+
+### Mocking
+
+For unit tests, mock external dependencies:
+
+```typescript
+import { vi } from 'vitest';
+
+const mockFunction = vi.fn(() => 'mocked value');
+```
+
+## Test Coverage Goals
+
+We aim for the following coverage targets:
+
+- **Statements:** > 80%
+- **Branches:** > 75%
+- **Functions:** > 80%
+- **Lines:** > 80%
+
+## Best Practices
+
+1. **Descriptive test names:** Use clear, descriptive names that explain what is being tested
+2. **One assertion per test:** Focus each test on a single behavior
+3. **Avoid test interdependence:** Tests should be able to run in any order
+4. **Clean up resources:** Always close servers, connections, and clean up after tests
+5. **Use appropriate timeouts:** Set reasonable timeouts for async operations
+6. **Test edge cases:** Include tests for error conditions and edge cases
+7. **Keep tests fast:** Unit tests should run in milliseconds, integration tests in seconds
+
+## Debugging Tests
+
+### Run a single test
+
+```bash
+yarn test -t "specific test name"
+```
+
+### Run with verbose output
+
+```bash
+yarn test --reporter=verbose
+```
+
+### Debug in VS Code
+
+Add a breakpoint and use the "Debug Test" option in VS Code's test explorer.
+
+## Continuous Integration
+
+Tests are automatically run in CI/CD pipelines on:
+
+- Pull requests
+- Commits to main branch
+- Release builds
+
+All tests must pass before code can be merged.
+
+## Contributing
+
+When adding new features:
+
+1. Write tests first (TDD approach recommended)
+2. Ensure all existing tests pass
+3. Add tests for edge cases
+4. Update this README if adding new test categories
+5. Maintain or improve code coverage
+
+## Troubleshooting
+
+### Port conflicts
+
+If tests fail due to port conflicts, the test suite uses high port numbers (9876-9894) to avoid conflicts. If you still experience issues, check for processes using these ports:
+
+```bash
+lsof -i :9876-9894
+```
+
+### Timeout errors
+
+If tests timeout, increase the timeout in `vitest.config.ts` or for specific tests:
+
+```typescript
+it('slow test', async () => {
+  // test code
+}, 30000); // 30 second timeout
+```
+
+### WebSocket connection issues
+
+WebSocket tests may fail if connections aren't properly closed. Ensure all WebSocket connections are explicitly closed in test cleanup.
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
+- [Node.js HTTP/2 Documentation](https://nodejs.org/api/http2.html)
+- [WebSocket API Documentation](https://github.com/websockets/ws)

package/tests/docker/README.md

@@ -0,0 +1,303 @@
+# Docker Tests
+
+This directory contains Docker integration tests for the Robiki Proxy.
+
+## Test Scripts
+
+### 1. `test-docker.sh`
+
+Comprehensive Docker build and runtime tests.
+
+**What it tests:**
+
+- Docker image builds successfully
+- Container starts and stays running
+- Configuration is loaded correctly
+- Ports are accessible
+- Environment variables are set
+- Health checks work
+- Graceful shutdown
+
+**Usage:**
+
+```bash
+./tests/docker/test-docker.sh
+```
+
+Or using Make:
+
+```bash
+make test-docker-full
+```
+
+### 2. `test-config-loading.sh`
+
+Tests specifically for proxy.config.json loading.
+
+**What it tests:**
+
+- Empty routes configuration
+- Multiple routes configuration
+- CORS configuration
+- Wildcard routes
+- File permissions and readability
+- Configuration priority (file > env > defaults)
+
+**Usage:**
+
+```bash
+./tests/docker/test-config-loading.sh
+```
+
+Or using Make:
+
+```bash
+make test-docker-config
+```
+
+## Quick Test Commands
+
+### Build Docker Images
+
+```bash
+# Standard build (with dev dependencies for build process)
+make docker-build
+
+# Build with dev dependencies (for testing/development)
+make docker-build-dev
+
+# Build without dev dependencies (production-optimized)
+make docker-build-prod
+```
+
+### Build and Basic Test
+
+```bash
+make test-docker
+```
+
+### Full Integration Test
+
+```bash
+make test-docker-full
+```
+
+### Config Loading Test
+
+```bash
+make test-docker-config
+```
+
+### Docker Compose Test
+
+```bash
+make test-docker-compose
+```
+
+## Build Arguments
+
+The Dockerfile supports a build argument to control dependency installation:
+
+- `INSTALL_DEV_DEPS=true` (default) - Installs all dependencies including devDependencies. Required for building the application.
+- `INSTALL_DEV_DEPS=false` - Installs only production dependencies. Use this for ultra-minimal production images when you already have pre-built artifacts.
+
+**Examples:**
+
+```bash
+# Build with dev dependencies (default, includes build tools)
+docker build --build-arg INSTALL_DEV_DEPS=true -t robiki/proxy:latest .
+
+# Build without dev dependencies (smaller image, no build)
+docker build --build-arg INSTALL_DEV_DEPS=false -t robiki/proxy:prod .
+```
+
+**Note:** The default behavior (`INSTALL_DEV_DEPS=true`) is recommended for most use cases as it builds the application from source.
+
+## Manual Testing
+
+### 1. Build the Image
+
+```bash
+docker build -t robiki/proxy:test .
+```
+
+### 2. Create Test Config
+
+```bash
+cat > proxy.config.test.json <<EOF
+{
+  "routes": {
+    "test.local": {
+      "target": "httpbin.org:80"
+    }
+  }
+}
+EOF
+```
+
+### 3. Run Container
+
+```bash
+docker run -d \
+  --name test-proxy \
+  -p 8080:8080 \
+  -v $(pwd)/proxy.config.test.json:/usr/src/proxy.config.json:ro \
+  robiki/proxy:test
+```
+
+### 4. Check Logs
+
+```bash
+docker logs test-proxy
+```
+
+### 5. Test Connection
+
+```bash
+curl -v http://localhost:8080/get -H "Host: test.local"
+```
+
+### 6. Cleanup
+
+```bash
+docker stop test-proxy
+docker rm test-proxy
+rm proxy.config.test.json
+```
+
+## Configuration Examples
+
+### Minimal Config
+
+```json
+{
+  "routes": {
+    "example.com": {
+      "target": "localhost:3000"
+    }
+  }
+}
+```
+
+### With CORS
+
+```json
+{
+  "routes": {
+    "api.example.com": {
+      "target": "localhost:3000"
+    }
+  },
+  "cors": {
+    "origin": "*",
+    "credentials": true
+  }
+}
+```
+
+### With SSL (requires certificates)
+
+```json
+{
+  "ssl": {
+    "key": "/usr/src/certs/key.pem",
+    "cert": "/usr/src/certs/cert.pem",
+    "allowHTTP1": true
+  },
+  "routes": {
+    "secure.example.com": {
+      "target": "localhost:3000",
+      "ssl": true
+    }
+  }
+}
+```
+
+### With Wildcard Routes
+
+```json
+{
+  "routes": {
+    "*.api.example.com": {
+      "target": "localhost:4000"
+    },
+    "example.com": {
+      "target": "localhost:3000"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Container Won't Start
+
+```bash
+# Check logs
+docker logs <container-name>
+
+# Check if config file is mounted
+docker exec <container-name> ls -la /usr/src/proxy.config.json
+
+# Check if config is valid JSON
+docker exec <container-name> cat /usr/src/proxy.config.json | node -e "JSON.parse(require('fs').readFileSync(0, 'utf-8'))"
+```
+
+### Port Already in Use
+
+```bash
+# Find what's using the port
+lsof -i :8080
+
+# Use different port mapping
+docker run -p 9000:8080 ...
+```
+
+### Config Not Loading
+
+```bash
+# Verify environment variable
+docker exec <container-name> env | grep PROXY_CONFIG
+
+# Check file permissions
+docker exec <container-name> ls -la /usr/src/proxy.config.json
+
+# Test config parsing
+docker exec <container-name> node -e "console.log(require('/usr/src/proxy.config.json'))"
+```
+
+## CI/CD Integration
+
+These tests are designed to run in CI/CD pipelines. See `.github/workflows/test.yml` for GitHub Actions integration.
+
+### Expected Test Results
+
+- ✅ All tests should pass on `main` branch
+- ✅ Docker build should complete in < 2 minutes
+- ✅ Container should start in < 10 seconds
+- ✅ All ports should be accessible
+- ✅ Configuration should load without errors
+
+## Performance Benchmarks
+
+Expected resource usage:
+
+- **Build time**: < 2 minutes
+- **Image size**: ~200-300 MB
+- **Memory usage**: ~50-100 MB
+- **CPU usage**: < 5% idle
+- **Startup time**: < 10 seconds
+
+## Security Notes
+
+- Container runs as non-root user (`node`)
+- Uses `dumb-init` for proper signal handling
+- Configuration files should be mounted read-only (`:ro`)
+- Secrets should be passed via environment variables or Docker secrets
+- Health checks are enabled by default
+
+## Further Reading
+
+- [Dockerfile](../../Dockerfile)
+- [docker-compose.yml](../../docker-compose.yml)
+- [Main README](../../README.md)