shittyserverless/README.md

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.

Most notable use being ChattedRooms' newest API rendition.

---

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:

git clone https://github.com/yourusername/shitty-serverless.git
cd shitty-serverless

2. Install dependencies:

npm install

3. Configure your environment by editing config.sample.js and then renaming it to config.js:

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:

node index.js

2. Open your browser or use curl:

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) 🐍

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:

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.