first commit

s3-nodejs-api/README.md

@@ -0,0 +1,104 @@
+# s3-audio-streamer
+
+This project is designed to stream audio files in M4A format stored in AWS S3. It utilizes an Express.js server to handle streaming requests and serves audio files efficiently.
+
+## Project Structure
+
+- **src/**: Contains the source code for the application.
+  - **app.ts**: Entry point of the application, initializes the Express app and sets up middleware and routes.
+  - **controllers/**: Contains the StreamController which handles streaming requests.
+  - **routes/**: Defines the routes for the application, including streaming routes.
+  - **services/**: Contains the S3Client for interacting with AWS S3 and the StreamService for processing streaming requests.
+  - **middlewares/**: Includes middleware for error handling and request logging.
+  - **utils/**: Contains utility functions, such as range parsing for streaming.
+  - **types/**: Defines TypeScript interfaces used throughout the application.
+
+- **k8s/**: Contains Kubernetes configuration files for deploying the application.
+  - **configmap.yaml**: ConfigMap for storing configuration data.
+  - **deployment.yaml**: Deployment configuration for the application.
+  - **hpa.yaml**: Horizontal Pod Autoscaler configuration.
+  - **ingress.yaml**: Ingress resource for routing external traffic.
+  - **secret.yaml**: Secret for storing sensitive information.
+  - **service.yaml**: Service resource for exposing the application.
+
+## Setup Instructions
+
+1. **Clone the repository**:
+   ```
+   git clone <repository-url>
+   cd s3-audio-streamer
+   ```
+
+2. **Install dependencies**:
+   ```
+   npm install
+   ```
+
+3. **Configure AWS credentials**:
+   Ensure that your AWS credentials are set up in the environment or in a configuration file.
+
+4. **Build the Docker image**:
+   ```
+   docker build -t s3-audio-streamer .
+   ```
+
+5. **Deploy to Kubernetes**:
+   Apply the Kubernetes configurations:
+   ```
+   kubectl apply -f k8s/
+   ```
+
+## Configuration
+
+Environment variables used by the service:
+
+- S3_BUCKET: Name of the bucket that stores your audio files (required).
+- AWS_REGION: AWS region (e.g., us-east-1). Required for AWS S3.
+- S3_ENDPOINT: Optional custom S3-compatible endpoint (e.g., http://minio.minio.svc.cluster.local:9000) for MinIO/self-hosted.
+- S3_FORCE_PATH_STYLE: "true" for MinIO; for AWS S3 use "false" or omit.
+- S3_PREFIX: Optional key prefix/folder within the bucket (e.g., current). If set, the service will request `S3_PREFIX/<fileName>`.
+- AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: Credentials to access S3/MinIO.
+- PORT: Port the server listens on (default 3000).
+
+Kubernetes wiring:
+
+- ConfigMap `audio-streamer-config` provides S3_BUCKET, AWS_REGION, S3_ENDPOINT, S3_FORCE_PATH_STYLE, and PORT.
+- Secret `aws-secret` provides access-key-id and secret-access-key.
+- Deployment consumes both via `env` refs and exposes port 3000.
+- Service `s3-audio-streamer` exposes the pod on port 3000.
+- Ingress `audio-streamer-ingress` routes HTTP traffic to the Service.
+
+Health endpoints:
+
+- GET `/` -> 200 OK (simple health)
+- GET `/healthz` -> 200 OK JSON { status: 'ok' }
+
+Streaming endpoint:
+
+- GET `/api/streams/:fileName` streams the M4A file with optional `Range` header for byte-range requests.
+
+Example MinIO configuration in ConfigMap:
+
+```
+S3_BUCKET=my-audio
+AWS_REGION=us-east-1
+S3_ENDPOINT=http://minio.minio.svc.cluster.local:9000
+S3_FORCE_PATH_STYLE=true
+S3_PREFIX=current
+PORT=3000
+```
+
+Remember to base64-encode values for the Secret:
+
+```
+echo -n 'minio' | base64   # access-key-id
+echo -n 'minio123' | base64 # secret-access-key
+```
+
+## Usage
+
+Once deployed, the application will be accessible via the configured Ingress. You can stream audio files by sending requests to the appropriate endpoints defined in the routes.
+
+## License
+
+This project is licensed under the MIT License.