2025-09-13 20:58:45 +02:00
# ShittyServerless Execution Instance 🛠️
**A lightweight Node.js server for executing serverless functions locally or via S3 storage.**
This project allows developers to deploy and run serverless functions by simply placing files in a storage backend (local filesystem or S3/MinIO). It handles streaming headers, request data, and safe child process execution.
2025-09-13 21:09:05 +02:00
Most notable use being ChattedRooms' newest API rendition.
2025-09-13 20:58:45 +02:00
---
## Features ✨
- Execute serverless functions in **Python, Node.js, or Bash ** automatically.
- Supports **local filesystem ** or **S3-compatible storage ** (e.g., AWS S3, MinIO).
- **Safe child process execution** with timeout handling.
- **Streaming response support** with header parsing and body streaming.
- Flexible **file lookup by extension ** or brute-force search.
- Easy integration with **existing serverless workflows ** .
---
## Prerequisites 📝
- Node.js v18+
- NPM (Node Package Manager)
- Optional: AWS credentials and S3 bucket if not using local storage
---
## Installation ⚡
1. Clone the repository:
```bash
git clone https://github.com/yourusername/shitty-serverless.git
cd shitty-serverless
```
2. Install dependencies:
```bash
npm install
```
3. Configure your environment by editing `config.sample.js` and then renaming it to `config.js` :
```bash
cp config.sample.js config.js
# Then edit config.js to match your setup
```
> ⚠️ Using local storage is **not recommended for production**.
---
## Usage 🚀
1. Start the server:
```bash
node index.js
```
2. Open your browser or use `curl` :
```bash
curl http://localhost:3000/yourFunction.py
```
- The server will attempt to execute the requested file if it exists in storage.
- Supported file extensions:
- `.sh` → Bash
- `.py` → Python 3
- `.js` → Node.js
3. If the requested file does not exist, the server will try a **brute-force search ** by appending supported extensions.
---
## Example Function (Python) 🐍
```python
import json
import sys
print("Content-Type: application/json")
req = json.loads(input('!!RECVDATA').strip()) # You can only ask for JSON data before body output
print("!!STARTBODY", end="") # No newline, avoids blank line before body
print(json.dumps(req), end="") # Echo back request data
sys.exit(2) # Exit code 2 means 403 Forbidden, but here it is just an example
```
- Place this file in `localstorage/` or S3 bucket.
- Request via HTTP:
```bash
curl http://localhost:3000/example.py
```
- Response will include headers and body streamed directly from the function.
---
## Exit Code Mapping 📊
The server maps child process exit codes to HTTP status codes:
| Exit Code | HTTP Status |
|-----------|-------------|
| 0 | 200 OK |
| 1 | 500 Internal Server Error |
| 2 | 403 Forbidden |
| 3 | 401 Unauthorized |
| 4 | 404 Not Found |
Other codes default to **500 Internal Server Error ** .
---
## Development Tips 💡
- For **debugging ** , all child process `stdout` and `stderr` are logged to the server console.
- Ensure your serverless scripts **emit the `!!STARTBODY` token ** to separate headers from body content.
- Use `!!RECVDATA` in scripts to access the incoming HTTP request object.
---
## License 🛡️
This project is provided **as-is ** , without warranty. Use at your own risk.
