Stream files directly from AWS S3 to your users without downloading them to your server first.
s3proxy turns any S3 bucket into a high-performance web server. Perfect for serving static websites, file downloads, or media content directly from S3 while maintaining full control over access, headers, and routing.
s3proxy v3.0.0+ is ESM-only and requires Node.js 22.13.0+
If you're upgrading from v2.x:
// ❌ v2.x (CommonJS) - No longer supported
const { S3Proxy } = require('s3proxy');
// ✅ v3.x (ESM) - New syntax
import { S3Proxy } from 's3proxy';
For CommonJS projects, you have two options:
"type": "module" to your package.jsonconst { S3Proxy } = await import('s3proxy');npm install s3proxy express
import express from 'express';
import { S3Proxy } from 's3proxy';
const app = express();
const proxy = new S3Proxy({ bucket: 'your-bucket-name' });
await proxy.init();
app.get('/*', async (req, res) => {
const stream = await proxy.get(req, res);
stream.on('error', err => res.status(err.statusCode || 500).end()).pipe(res);
});
app.listen(3000);
npm install s3proxy express
npm install --save-dev @types/express
import express from 'express';
import { S3Proxy } from 's3proxy';
import type { HttpRequest, HttpResponse } from 's3proxy';
const app = express();
const proxy = new S3Proxy({ bucket: 'your-bucket-name' });
await proxy.init();
app.get('/*', async (req, res) => {
try {
const stream = await proxy.get(req as HttpRequest, res as HttpResponse);
stream.on('error', (err: any) => {
res.status(err.statusCode || 500).end();
}).pipe(res);
} catch (error) {
res.status(500).json({ error: 'Failed to fetch file' });
}
});
app.listen(3000);
Now curl http://localhost:3000/index.html serves s3://your-bucket-name/index.html
import express, { type Request, type Response } from 'express';
import { S3Proxy } from 's3proxy';
import type { HttpRequest, HttpResponse } from 's3proxy';
const app = express();
const proxy = new S3Proxy({
bucket: 'my-website-bucket',
region: 'us-west-2'
});
// Initialize with proper error handling
try {
await proxy.init();
console.log('S3Proxy initialized successfully');
} catch (error) {
console.error('Failed to initialize S3Proxy:', error);
process.exit(1);
}
// Error handler
function handleError(req: Request, res: Response, err: any): void {
const statusCode = err.statusCode || 500;
const errorXml = `<?xml version="1.0"?>
<error code="${err.code || 'InternalError'}" statusCode="${statusCode}" url="${req.url}">${err.message}</error>`;
res.status(statusCode).type('application/xml').send(errorXml);
}
// Serve all files from S3
app.get('/*', async (req: Request, res: Response) => {
try {
const stream = await proxy.get(req as HttpRequest, res as HttpResponse);
stream.on('error', (err) => {
handleError(req, res, err);
}).pipe(res);
} catch (err) {
handleError(req, res, err);
}
});
app.listen(3000);
s3proxy automatically handles HTTP Range requests for efficient streaming of large files:
# Download only bytes 0-99 of a large file
curl --range 0-99 http://localhost:3000/large-video.mp4 -o partial.mp4
Built-in health check endpoint for load balancers:
app.get('/health', async (req: Request, res: Response) => {
try {
const stream = await proxy.healthCheckStream(res as HttpResponse);
stream.on('error', () => res.end()).pipe(res);
} catch (error) {
res.status(500).end();
}
});
import { S3Proxy } from 's3proxy';
import type { S3ProxyConfig } from 's3proxy';
const config: S3ProxyConfig = {
bucket: 'my-bucket', // Required: S3 bucket name
region: 'us-west-2', // Optional: AWS region
credentials: { // Optional: AWS credentials
accessKeyId: 'AKIA...',
secretAccessKey: '...'
},
endpoint: 'https://...', // Optional: Custom S3 endpoint
maxAttempts: 3, // Optional: Retry attempts
requestTimeout: 30000 // Optional: Request timeout in ms
};
const proxy = new S3Proxy(config);
BUCKET - S3 bucket namePORT - Server port (default: 3000)AWS_REGION - AWS regionNODE_ENV - Environment (enables credential file in dev mode)new S3Proxy(config: S3ProxyConfig)
await proxy.init(): Promise<void>Initialize S3 client and verify bucket access. Must be called before using other methods.
await proxy.get(req: HttpRequest, res: HttpResponse): Promise<Readable>Stream S3 object to HTTP response. Handles range requests automatically.
await proxy.head(req: HttpRequest, res: HttpResponse): Promise<Readable>Get object metadata (HEAD request). Returns empty stream with headers set.
await proxy.healthCheck(): Promise<void>Verify bucket connectivity. Throws error if bucket is inaccessible.
await proxy.healthCheckStream(res: HttpResponse): Promise<Readable>Health check with streaming response. Sets appropriate status code and headers.
S3Proxy.version(): stringReturns the current version of s3proxy.
S3Proxy.parseRequest(req: HttpRequest): ParsedRequestParse HTTP request to extract S3 key and query parameters.
interface S3ProxyConfig extends S3ClientConfig {
bucket: string;
}
interface HttpRequest extends IncomingMessage {
path?: string;
query?: Record<string, string | string[]>;
headers: Record<string, string | string[]>;
url: string;
method?: string;
}
interface HttpResponse extends ServerResponse {
writeHead(statusCode: number, headers?: any): this;
}
interface ParsedRequest {
key: string;
query: Record<string, string | string[]>;
}
s3proxy emits events for monitoring:
proxy.on('error', (err: Error) => {
console.error('S3Proxy error:', err);
});
proxy.on('init', () => {
console.log('S3Proxy initialized successfully');
});
For containerized deployments:
docker run --env BUCKET=mybucket --env PORT=8080 --publish 8080:8080 -t forkzero/s3proxy:3.0.0
For local development with temporary AWS credentials:
aws sts get-session-token --duration 900 > credentials.json
docker run \
-v $PWD/credentials.json:/src/credentials.json:ro \
-e BUCKET=mybucket \
-e PORT=8080 \
-e NODE_ENV=dev \
-p 8080:8080 \
-t forkzero/s3proxy:3.0.0
# Install dependencies
npm install
# Development with hot reload
npm run dev
# Build TypeScript
npm run build
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Type checking
npm run type-check
s3proxy maintains comprehensive test coverage across multiple dimensions to ensure reliability and performance:
| Test Type | Local (Makefile) | CI (GitHub Actions) | Description |
|---|---|---|---|
| Code Quality | |||
| Lint | make lint | ✅ Node CI | Code style and quality checks |
| Type Check | make type-check | ✅ Node CI | TypeScript type safety validation |
| Security Audit | npm audit | ✅ Node CI | Dependency vulnerability scanning |
| Unit Testing | |||
| Unit Tests | make unit-tests | ✅ Node CI | Core functionality testing |
| Coverage | npm run test:coverage | ✅ Node CI | Code coverage reporting (96%+) |
| Integration Testing | |||
| Build Verification | make build | ✅ Node CI | TypeScript compilation |
| Package Verification | make pre-release-check | ✅ Node CI | npm package integrity |
| Functional Testing | |||
| Validation Tests | make test-validation-docker | ✅ Node CI | 24 comprehensive functionality tests |
| Binary Integrity | Included in validation | ✅ Node CI | File corruption detection |
| Range Requests | Included in validation | ✅ Node CI | HTTP range request handling |
| Error Handling | Included in validation | ✅ Node CI | Proper error status codes |
| Performance Testing | |||
| Load Testing | make artillery-docker | ✅ Node CI | High-throughput performance |
| Stress Testing | make test-performance | ✅ Node CI | Resource usage under load |
| Platform Testing | |||
| Docker Integration | make test-all-docker | ✅ Node CI | Containerized deployment |
| Multi-Node | Node 22, 23 | ✅ Node CI | Cross-version compatibility |
# Run all tests locally
make all # Complete test suite
make test # Core tests (build, lint, unit)
make functional-tests # Integration and Docker tests
# Individual test categories
make test-validation-docker # 24 comprehensive validation tests
make artillery-docker # Performance/load testing
# Quality checks
make pre-release-check # Complete pre-release verification
src/
├── index.ts # Main S3Proxy class
├── UserException.ts # Custom error class
└── types.ts # Type definitions
examples/
├── express-basic.ts # TypeScript Express example
└── http.ts # TypeScript HTTP example
test/
├── s3proxy.test.ts # Main functionality tests
├── parseRequest.test.ts # Request parsing tests
├── MockExpress.test.ts # Express integration tests
└── integration/
└── validation.test.js # End-to-end validation tests
s3proxy uses several configuration files for different aspects of development and deployment:
tsconfig.json - Main TypeScript compiler configuration
src/ to dist/src/ for npm packagetsconfig.examples.json - Type checking for examples
npm run type-check to validate examplesvitest.config.ts - Unit test configuration
vitest.integration.config.ts - Integration test configuration
npm run test:validation and Makefile targetsbiome.json - Code formatting and linting
.releaserc.json - Semantic release configuration
.github/workflows/nodejs.yml - Main CI pipeline
.github/workflows/release.yml - Automated releases.github/workflows/manual-release.yml - Manual release workflowshared-testing/configs/ - Artillery load test configurations
load-test.yml - Main load testing config (used in Makefile)docker-container.yml - Docker-specific load testingnpm-package.yml - NPM package load testingperformance-comparison.yml - Performance benchmarkingshared-testing/scenarios/ - Artillery test scenarios
load-test.yml - Basic load testing scenariosbasic-load.yml - Simple load patternssustained-load.yml - Extended load testingspike-load.yml - Traffic spike simulationrange-requests.yml - HTTP range request testing.vscode/settings.json - VS Code workspace settings
.github/dependabot.yml - Automated dependency updatesMakefile - Build automation and testing orchestration
examples/aws-ecs/ - ECS deployment configurations
All configuration files are actively maintained and serve specific purposes in the development, testing, and deployment pipeline.
See PERFORMANCE.md for detailed performance testing and benchmarks.
We welcome contributions! See our Maintenance Guide for development setup and contribution guidelines.
Apache 2.0 - see LICENSE file.
FAQs
Streaming web proxy for AWS S3
The npm package s3proxy receives a total of 207 weekly downloads. As such, s3proxy popularity was classified as not popular.
We found that s3proxy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
/Security News
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.
Research
/Security News
Socket researchers investigate 4 malicious npm and PyPI packages with 56,000+ downloads that install surveillance malware.