{"id":35120473,"url":"https://github.com/pardnchiu/go-faas","last_synced_at":"2026-02-01T11:20:35.394Z","repository":{"id":330873794,"uuid":"1074090381","full_name":"pardnchiu/go-faas","owner":"pardnchiu","description":"Run Py/JS/TS functions as serverless endpoints","archived":false,"fork":false,"pushed_at":"2026-01-04T08:51:08.000Z","size":130,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-13T22:55:16.482Z","etag":null,"topics":["backend","faas","golang","pardnchiu"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pardnchiu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-11T06:05:40.000Z","updated_at":"2026-01-07T13:41:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pardnchiu/go-faas","commit_stats":null,"previous_names":["pardnchiu/go-faas"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/pardnchiu/go-faas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pardnchiu%2Fgo-faas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pardnchiu%2Fgo-faas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pardnchiu%2Fgo-faas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pardnchiu%2Fgo-faas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pardnchiu","download_url":"https://codeload.github.com/pardnchiu/go-faas/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pardnchiu%2Fgo-faas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28977318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T11:15:31.175Z","status":"ssl_error","status_checked_at":"2026-02-01T11:14:42.175Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","faas","golang","pardnchiu"],"created_at":"2025-12-27T23:42:31.467Z","updated_at":"2026-02-01T11:20:35.389Z","avatar_url":"https://github.com/pardnchiu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!NOTE]\n\u003e This README was generated by [Claude Code](https://github.com/pardnchiu/skill-readme-generate), get the ZH version from [here](./README.zh.md).\n\n![cover](./cover.png)\n\n# go-faas\n\n[![pkg](https://pkg.go.dev/badge/github.com/pardnchiu/go-faas.svg)](https://pkg.go.dev/github.com/pardnchiu/go-faas)\n[![card](https://goreportcard.com/badge/github.com/pardnchiu/go-faas)](https://goreportcard.com/report/github.com/pardnchiu/go-faas)\n[![version](https://img.shields.io/github/v/tag/pardnchiu/go-faas?label=release)](https://github.com/pardnchiu/go-faas/releases)\n[![license](https://img.shields.io/github/license/pardnchiu/go-faas)](LICENSE)\n\n\u003e Lightweight Golang FaaS platform providing isolated execution environments for JavaScript, TypeScript, and Python scripts. Uses bubblewrap sandbox with systemd-run resource limits for secure script execution without containers.\n\n## Table of Contents\n\n- [Features](#features)\n- [Architecture](#architecture)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API Reference](#api-reference)\n- [Script Examples](#script-examples)\n- [License](#license)\n- [Author](#author)\n- [Stars](#stars)\n\n## Features\n\n- **Multi-language Support**: Execute JavaScript, TypeScript, and Python scripts with unified JSON parameter passing and result return\n- **Sandbox Isolation**: Uses bubblewrap (bwrap) with Linux namespaces to isolate execution environments and protect the host system\n- **Resource Limits**: Control CPU and memory usage via systemd-run to prevent malicious scripts from exhausting system resources\n- **Version Management**: Scripts are automatically versioned and stored in Redis; execute specific versions or use the latest\n- **Streaming Output**: Support SSE streaming mode for real-time script execution progress and log output\n\n## Architecture\n\n```mermaid\nflowchart TD\n    subgraph HTTP[\"HTTP Layer\"]\n        A[HTTP Request] --\u003e B{Gin Router}\n        B --\u003e|POST /upload| C[Upload Handler]\n        B --\u003e|POST /run/*| D[Run Handler]\n        B --\u003e|POST /run-now| E[RunNow Handler]\n    end\n\n    subgraph Storage[\"Storage Layer\"]\n        C --\u003e F[Validate Language/Path]\n        F --\u003e G[(Redis)]\n        G --\u003e|meta:hash| H[Path/Language/Latest Version]\n        G --\u003e|code:hash:ts| I[Script Source Code]\n    end\n\n    subgraph Execution[\"Execution Layer\"]\n        D --\u003e J[Get Script from Redis]\n        J --\u003e K[Create Sandbox Command]\n        E --\u003e K\n\n        K --\u003e L[systemd-run]\n        L --\u003e|CPUQuota| M[CPU Limit]\n        L --\u003e|MemoryMax| N[Memory Limit]\n\n        L --\u003e O[bubblewrap]\n        O --\u003e|--unshare-all| P[Namespace Isolation]\n        O --\u003e|--unshare-net| Q[Network Isolation]\n        O --\u003e|--ro-bind| R[Read-only Mount /usr /lib]\n        O --\u003e|--cap-drop ALL| S[Drop All Capabilities]\n    end\n\n    subgraph Runtime[\"Runtime Layer\"]\n        O --\u003e T{Language Detection}\n        T --\u003e|javascript| U[node wrapper.js]\n        T --\u003e|typescript| V[tsx wrapper.ts]\n        T --\u003e|python| W[python3 wrapper.py]\n\n        U --\u003e X[stdin: JSON Payload]\n        V --\u003e X\n        W --\u003e X\n        X --\u003e Y[Execute User Script]\n        Y --\u003e Z[stdout: Result]\n    end\n\n    Z --\u003e AA{Stream Mode?}\n    AA --\u003e|Yes| AB[SSE Stream Response]\n    AA --\u003e|No| AC[JSON Response]\n```\n\n## Installation\n\n### Requirements\n\n- Go 1.23.0+\n- Redis 6.0+\n- Linux (requires bubblewrap and systemd)\n- Node.js 22+\n- Python 3.10+\n\n### System Dependencies\n\n```bash\n# Ubuntu / Debian\nsudo apt update\nsudo apt install -y bubblewrap redis-server nodejs npm python3\n\n# Fedora / RHEL\nsudo dnf install -y bubblewrap redis nodejs npm python3\n\n# Arch Linux\nsudo pacman -S bubblewrap redis nodejs npm python\n```\n\n### Setup\n\n```bash\ngit clone https://github.com/pardnchiu/go-faas.git\ncd go-faas\n\n# Install Go dependencies\ngo mod download\n\n# Install Node.js dependencies (esbuild for TypeScript compilation)\nnpm install\n\n# Install tsx (TypeScript executor)\nnpm install -g tsx\n```\n\n### Start Service\n\n```bash\n# Ensure Redis is running\n\n# Start FaaS service\ngo run cmd/api/main.go\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HTTP_PORT` | `8080` | HTTP service port |\n| `MAX_CPUS` | `1` | CPU quota per sandbox (100% = 1 core) |\n| `MAX_MEMORY` | `128M` | Memory limit per sandbox |\n| `CODE_MAX_SIZE` | `262144` | Maximum code size (bytes) |\n| `TIMEOUT_SCRIPT` | `30` | Script execution timeout (seconds) |\n| `REDIS_HOST` | `localhost` | Redis host |\n| `REDIS_PORT` | `6379` | Redis port |\n| `REDIS_PASSWORD` | empty | Redis password |\n| `REDIS_DB` | `0` | Redis database number |\n\n## Usage\n\n### Execute Script Immediately\n\n```bash\ncurl -X POST http://localhost:8080/run-now \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"language\": \"javascript\",\n    \"code\": \"return { sum: event.a + event.b };\",\n    \"input\": \"{\\\"a\\\": 10, \\\"b\\\": 5}\"\n  }'\n```\n\nResponse:\n\n```json\n{\n  \"data\": { \"sum\": 15 },\n  \"type\": \"json\"\n}\n```\n\n### Upload and Execute Script\n\n```bash\n# Upload script\ncurl -X POST http://localhost:8080/upload \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"path\": \"math/add\",\n    \"language\": \"javascript\",\n    \"code\": \"return { result: event.a + event.b };\"\n  }'\n\n# Execute saved script\ncurl -X POST http://localhost:8080/run/math/add \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"input\": { \"a\": 10, \"b\": 5 } }'\n```\n\n### Streaming Mode\n\n```bash\ncurl -X POST http://localhost:8080/run-now \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"language\": \"python\",\n    \"code\": \"import json\\nfor i in range(3):\\n  print(json.dumps({\\\"progress\\\": i}))\\nreturn {\\\"done\\\": True}\",\n    \"input\": \"{}\",\n    \"stream\": true\n  }'\n```\n\n## API Reference\n\n### POST /upload\n\nUpload and store a script in Redis.\n\n**Request Body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `path` | string | Yes | Script path identifier |\n| `language` | string | Yes | `javascript`, `typescript`, or `python` |\n| `code` | string | Yes | Script source code |\n\n**Response:**\n\n```json\n{\n  \"path\": \"math/add\",\n  \"language\": \"javascript\",\n  \"version\": 1735286400\n}\n```\n\n### POST /run/{path}\n\nExecute an uploaded script.\n\n**Query Parameters:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `version` | Specify version timestamp (optional, defaults to latest) |\n\n**Request Body:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `input` | object/string | Input data passed to the script |\n| `stream` | boolean | Enable SSE streaming mode |\n\n### POST /run-now\n\nExecute a script immediately without storing.\n\n**Request Body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `language` | string | Yes | `javascript`, `typescript`, or `python` |\n| `code` | string | Yes | Script source code |\n| `input` | string | No | JSON formatted input data |\n| `stream` | boolean | No | Enable SSE streaming mode |\n\n## Script Examples\n\nAll scripts receive input data via the `event` variable.\n\n### JavaScript\n\n```javascript\nconst result = {\n  sum: event.a + event.b,\n  product: event.a * event.b\n};\nreturn result;\n```\n\n### TypeScript\n\n```typescript\ninterface Event {\n  a: number;\n  b: number;\n}\n\nconst result = {\n  sum: event.a + event.b,\n  product: event.a * event.b\n};\nreturn result;\n```\n\n### Python\n\n```python\nresult = {\n    'sum': event['a'] + event['b'],\n    'product': event['a'] * event['b']\n}\nreturn result\n```\n\n## License\n\nThis project is licensed under [MIT](LICENSE).\n\n## Author\n\n\u003cimg src=\"https://avatars.githubusercontent.com/u/25631760\" align=\"left\" width=\"96\" height=\"96\" style=\"margin-right: 0.5rem;\"\u003e\n\n\u003ch4 style=\"padding-top: 0\"\u003e邱敬幃 Pardn Chiu\u003c/h4\u003e\n\n\u003ca href=\"mailto:dev@pardn.io\" target=\"_blank\"\u003e\n\u003cimg src=\"https://pardn.io/image/email.svg\" width=\"48\" height=\"48\"\u003e\n\u003c/a\u003e \u003ca href=\"https://linkedin.com/in/pardnchiu\" target=\"_blank\"\u003e\n\u003cimg src=\"https://pardn.io/image/linkedin.svg\" width=\"48\" height=\"48\"\u003e\n\u003c/a\u003e\n\n## Stars\n\n[![Star](https://api.star-history.com/svg?repos=pardnchiu/go-faas\u0026type=Date)](https://www.star-history.com/#pardnchiu/go-faas\u0026Date)\n\n***\n\n©️ 2025 [邱敬幃 Pardn Chiu](https://linkedin.com/in/pardnchiu)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpardnchiu%2Fgo-faas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpardnchiu%2Fgo-faas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpardnchiu%2Fgo-faas/lists"}