{"id":21206073,"url":"https://github.com/bots-garden/simplism","last_synced_at":"2025-07-10T08:32:47.789Z","repository":{"id":207113505,"uuid":"718462201","full_name":"bots-garden/simplism","owner":"bots-garden","description":"A tiny HTTP server for Extism Wasm Plug-ins | a cloud-native runtime for Extism Wasm nanoservices plug-ins","archived":false,"fork":false,"pushed_at":"2024-03-22T14:00:57.000Z","size":1819,"stargazers_count":37,"open_issues_count":35,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-03T05:45:05.405Z","etag":null,"topics":["extism","faas","wasi","wasm","webassembly"],"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/bots-garden.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}},"created_at":"2023-11-14T05:58:12.000Z","updated_at":"2024-07-10T02:21:09.000Z","dependencies_parsed_at":"2023-12-29T08:33:14.781Z","dependency_job_id":"418b2903-fec6-4d4d-ac8b-49c4f48f9a60","html_url":"https://github.com/bots-garden/simplism","commit_stats":null,"previous_names":["bots-garden/simplism"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bots-garden%2Fsimplism","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bots-garden%2Fsimplism/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bots-garden%2Fsimplism/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bots-garden%2Fsimplism/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bots-garden","download_url":"https://codeload.github.com/bots-garden/simplism/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225629896,"owners_count":17499294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["extism","faas","wasi","wasm","webassembly"],"created_at":"2024-11-20T20:54:08.163Z","updated_at":"2024-11-20T20:54:08.728Z","avatar_url":"https://github.com/bots-garden.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simplism: a tiny HTTP server for Extism Plug-ins\n\n![image](imgs/simplism-small-logo.jpeg)\n\n## What is Simplism?\n\n**Simplism** is a tiny HTTP server to serve [Extism](https://extism.org/) WebAssembly plug-ins and execute/call a single WebAssembly function.\n\n\u003e It's like the official [Extism CLI](https://github.com/extism/cli), but **Simplism** is \"serving\" the Extism WebAssembly plug-in instead of running it, and call a function at every HTTP request.\n\n## 🚀 Getting started\n\n### Install Simplism\n\n```bash\nSIMPLISM_DISTRO=\"Linux_arm64\" # 👀 https://github.com/bots-garden/simplism/releases\nVERSION=\"0.1.3\"\nwget https://github.com/bots-garden/simplism/releases/download/v${VERSION}/simplism_${SIMPLISM_DISTRO}.tar.gz -O simplism.tar.gz \ntar -xf simplism.tar.gz -C /usr/bin\nrm simplism.tar.gz\nsimplism version\n```\n\n### Generate a (GoLang) wasm plug-in\n\n```bash\nsimplism generate golang hello ./\n\n# hello\n# ├── go.mod\n# ├── main.go\n# └── README.md\n```\n\n#### Build the wasm plug-in\n\u003e you can follow the instructions into the `hello/README.md` file\n\n```bash\ncd hello\ntinygo build -scheduler=none --no-debug \\\n-o hello.wasm \\\n-target wasi main.go\n```\n\n#### Serve the wasm plug-in\n\n```bash\nsimplism listen \\\nhello.wasm handle --http-port 8080 --log-level info\n```\n\n#### Query the wasm plug-in:\n\n```bash\ncurl http://localhost:8080/hello/world \\\n-H 'content-type: application/json; charset=utf-8' \\\n-d '{\"firstName\":\"Bob\",\"lastName\":\"Morane\"}'\n```\n\n## Run Simplism\n\n```text\nUsage:\n  simplism [command] [arguments]\n\nAvailable Commands:\n  listen      Serve an Extism plug-in function\n              Arguments: [wasm file path] [function name]\n  version     Display the Minism version\n              Arguments: nothing\n  generate    Generate a source code project of an Extism plug-in\n              Arguments: [plug-in language] [project name] [project path]\n              Languages: golang (or go), rustlang (or rust), javascript (or js)\n              Ex: simplism generate js hello samples/javascript (it will create samples/javascript/hello/)\n  config      Serve an Extism plug-in function using a yaml configuration file\n              Arguments: [yaml file path] [config key]\n  flock       Serve several Extism plug-in functions using a yaml configuration file\n              Arguments: [yaml file path] [config key]\n\nFlags for listen command:\n  --http-port              int      HTTP port of the Simplism server (default: 8080)\n  --log-level              string   Log level to print message\n                                    Possible values: error, warn, info, debug, trace\n  --allow-hosts            string   Hosts for HTTP request (json array) \n                                    Default: [\"*\"]\n  --allow-paths            string   Allowed paths to write and read files (json string) \n                                    Default: {}\n  --config                 string   Configuration data (json string)\n                                    Default: {}\n  --env                    string   Environment variables to forward to the wasm plug-in\n                                    Default: []\n  --wasi                   bool     Default: true\n  --wasm-url               string   Url to download the wasm file\n  --wasm-url-auth-header   string   Authentication header to download the wasm file, ex: \"PRIVATE-TOKEN=IlovePandas\"\n                                    Or use this environment variable: WASM_URL_AUTH_HEADER='PRIVATE-TOKEN=IlovePandas'\n  --cert-file              string   Path to certificate file (https)\n  --key-file               string   Path to key file (https)\n  --admin-reload-token     string   Admin token to be authorized to reload the wasm-plugin\n                                    Or use this environment variable: ADMIN_RELOAD_TOKEN\n                                    Use the /reload endpoint to reload the wasm-plugin\n  --service-discovery      bool     The current Simplism server is a service discovery server\n                                    Default: false\n  --discovery-endpoint     string   The endpoint of the service discovery server\n                                    It always ends with /discovery\n                                    Example: http://localhost:9000/discovery\n  --admin-discovery-token  string   Admin token to be authorized to post information to the service discovery server\n                                    Or use this environment variable: ADMIN_DISCOVERY_TOKEN\n                                    Use the /discovery endpoint to post information to the service discovery server\n  --service-name           string   Name of the service (it can be useful with the service discovery mode)\n  --information            string   Information about the service (it can be useful with the service discovery mode)\n  --spawn-mode             bool     The current Simplism server is in spawn mode (it can create new simplism servers with the /spawn endpoint)\n                                    Default: false\n  --admin-spawn-token      string   Admin token to be authorized to spawn a new Simplism server\n                                    Or use this environment variable: ADMIN_SPAWN_TOKEN\n                                    Use the /spawn endpoint to spawn a new Simplism server\n  --http-port-auto         bool     Automatically find an available port (only works in spawn mode)\n                                    Default: false\n  --recovery-path          string   Path of the recovery file (only works in spawn mode)\n                                    Default: \"recovery.yaml\"\n  --recovery-mode          bool     The current Simplism server is in recovery mode\n                                    Default: true\n  --store-mode             bool     The current Simplism server exposes a store api to save data in a bbolt database\n                                    Use the /store endpoint (see documentation)\n                                    Default: false\n  --store-path             string   File path of the store db file  \n                                    Default: file path of the wasm file + file name + \".store.db\"\n  --admin-store-token      string   Admin token to be authorized to use the store API of a Simplism server\n                                    Or use this environment variable: ADMIN_STORE_TOKEN\n  --registry-mode          bool     The current Simplism server exposes a registry api to upload wasm files\n                                    Use the /registry endpoint (see documentation)\n                                    Default: false\n  --registry-path          string   File path of the uploaded wasm files  \n  --admin-registry-token   string   Admin token to be authorized to use the registry API: POST(`/push`) and DELETE(`/remove`)\n                                    Or use this environment variable: ADMIN_REGISTRY_TOKEN\n  --private-registry-token string   Private registry token to be authorized to use the registry API: GET(`/pull`) and GET(`/discover`)\n                                    Or use this environment variable: PRIVATE_REGISTRY_TOKEN\n```\n\u003e *Remarks: look at the `./samples` directory*\n\n\u003e **Examples**:\n\n```bash\nsimplism listen ./samples/golang/simple-plugin/simple.wasm say_hello\n```\n\n```bash\nsimplism listen ./samples/golang/hello-plugin/simple.wasm say_hello \\\n--http-port 9090 \\\n--log-level info \\\n--allow-hosts '[\"*\",\"*.google.com\"]' \\\n--config '{\"message\":\"👋 hello world 🌍\"}' \\\n--allow-paths '{\"data\":\"/mnt\"}'\n```\n\n\u003e **Configuration example**:\n\n```yaml\n# config.yml\nhello-plugin:\n  wasm-file: ./hello.wasm\n  wasm-function: say_hello\n  http-port: 8080\n  log-level: info\n```\n\nRun the server like this: `simplism config ./config.yml hello-plugin`\n\n\u003e **Run Simplism in \"flock\" mode**:\n\n```yaml\n# config.yml\nhello-1:\n  wasm-file: ./hello.wasm\n  wasm-function: say_hello\n  http-port: 8081\n  log-level: info\nhello-2:\n  wasm-file: ./hello.wasm\n  wasm-function: say_hello\n  http-port: 8082\n  log-level: info\nhello-3:\n  wasm-file: ./hello.wasm\n  wasm-function: say_hello\n  http-port: 8083\n  log-level: info\n```\n\nRun the server**s** like this: `simplism flock ./config.yml`. It will start **3** instances of Simplism.\n\n\u003e See `samples/flock` repository for a more complex example.\n\n\n## Reload remotely a wasm plug-in without stopping the Simplism server\n\n### Start the Simplism server\n\n```bash\nsimplism listen ./hey-one.wasm handle --http-port 8080  --admin-reload-token \"1234567890\"\n```\n\nor\n\n```bash\nexport ADMIN_RELOAD_TOKEN=\"1234567890\"\nsimplism listen ./hey-one.wasm handle --http-port 8080\n```\n\n### Reload the wasm plug-in with the /reload api\n\n```bash\ncurl -v -X POST \\\nhttp://localhost:8080/reload \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-reload-token:1234567890' \\\n-d '{\"wasm-url\":\"http://0.0.0.0:3333/hey-two/hey-two.wasm\", \"wasm-file\": \"./hey-two.wasm\", \"wasm-function\": \"handle\"}'\n```\n\n## Service discovery\n\n\u003e 🚧 this is a work in progress\n\nSimplism comes with a service discovery feature. It can be used to discover the running Simplism servers.\n- One of the servers (simplism service) can be a service discovery server. The service discovery server can be configured with the `--service-discovery` flag:\n\n```bash\nsimplism listen discovery-service/discovery-service.wasm handle \\\n--http-port 9000 \\\n--log-level info \\\n--service-discovery true \\\n--admin-discovery-token people-are-strange\n```\n\u003e `--admin-discovery-token` is not mandatory, but it's probably a good idea to set it.\n\n- Then, the other services can be configured with the `--discovery-endpoint` flag:\n\n```bash\nsimplism listen service-one/service-one.wasm handle \\\n--http-port 8001 \\\n--log-level info \\\n--discovery-endpoint http://localhost:9000/discovery \\\n--admin-discovery-token people-are-strange \u0026\n\nsimplism listen service-two/service-two.wasm handle \\\n--http-port 8002 \\\n--log-level info \\\n--discovery-endpoint http://localhost:9000/discovery \\\n--admin-discovery-token people-are-strange \u0026\n\nsimplism listen service-three/service-three.wasm handle \\\n--http-port 8003 \\\n--log-level info \\\n--discovery-endpoint http://localhost:9000/discovery \\\n--admin-discovery-token people-are-strange \u0026\n```\n\u003e the 3 services will be discovered by the service discovery server. Every services will regularly post information to the service discovery server.\n\n- You can query the service discovery server with the `/discovery` endpoint to get the list of the running services:\n\n```bash\ncurl http://localhost:9000/discovery \\\n-H 'admin-discovery-token:people-are-strange'\n```\n\n- You can use the flock mode jointly with the service discovery:\n\n```yaml\nservice-discovery:\n  wasm-file: ./discovery/discovery.wasm\n  wasm-function: handle\n  http-port: 9000\n  log-level: info\n  service-discovery: true\n  admin-discovery-token: this-is-the-way\n\nbasestar-mother:\n  wasm-file: ./basestar/basestar.wasm\n  wasm-function: handle\n  http-port: 8010\n  log-level: info\n  discovery-endpoint: http://localhost:9000/discovery\n  admin-discovery-token: this-is-the-way\n\nraider-1:\n  wasm-file: ./raider/raider.wasm\n  wasm-function: handle\n  http-port: 8001\n  log-level: info\n  discovery-endpoint: http://localhost:9000/discovery\n  admin-discovery-token: this-is-the-way\n```\n\n## Spawn mode\n\n\u003e 🚧 this is a work in progress\n\nIf you activate the `--spawn-mode` flag, the Simplism server will be able tospawn a new Simplism server with the `/spawn` endpoint:\n\n```bash\nsimplism listen ./process-spawner.wasm handle \\\n--http-port 8000 \\\n--log-level info \\\n--spawn-mode true \\\n--admin-spawn-token michael-burnham-rocks\n```\n\nThen, to \"spawn\" a new Simplism server process, you can use the `/spawn` endpoint with a simple curl request:\n\n```bash\ncurl -X POST \\\nhttp://localhost:8080/spawn \\\n-H 'admin-spawn-token:michael-burnham-rocks' \\\n-H 'Content-Type: application/json; charset=utf-8' \\\n--data-binary @- \u003c\u003c EOF\n{\n    \"wasm-file\":\"../say-hello/say-hello.wasm\", \n    \"wasm-function\":\"handle\", \n    \"http-port\":\"9093\", \n    \"discovery-endpoint\":\"http://localhost:8080/discovery\", \n    \"admin-discovery-token\":\"michael-burnham-rocks\"\n}\nEOF\necho \"\"\n```\n\n## Expose and use the \"store API\"\n\n\u003e start a Simplism server with the `--store-mode` flag:\n```bash\nsimplism listen \\\nstore.wasm handle \\\n--http-port 8080 \\\n--log-level info \\\n--store-mode true \\\n--admin-store-token morrison-hotel \\\n--information \"👋 I'm the store service\"\n```\n\n### Query the \"store API\"\n\n\u003e add records to the store:\n```bash\ncurl http://localhost:8080/store \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-store-token: morrison-hotel' \\\n-d '{\"key\":\"hello\",\"value\":\"hello world\"}'\n\ncurl http://localhost:8080/store \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-store-token: morrison-hotel' \\\n-d '{\"key\":\"hey\",\"value\":\"hey people\"}'\n\ncurl http://localhost:8080/store \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-store-token: morrison-hotel' \\\n-d '{\"key\":\"001\",\"value\":\"first\"}'\n\ncurl http://localhost:8080/store \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-store-token: morrison-hotel' \\\n-d '{\"key\":\"002\",\"value\":\"second\"}'\n\ncurl http://localhost:8080/store \\\n-H 'content-type: application/json; charset=utf-8' \\\n-H 'admin-store-token: morrison-hotel' \\\n-d '{\"key\":\"003\",\"value\":\"third\"}'\n```\n\n\u003e get all records from the store:\n```bash\ncurl http://localhost:8080/store \\\n-H 'admin-store-token: morrison-hotel'\n```\n\n\u003e get a specific record from the store:\n```bash\ncurl http://localhost:8080/store?key=hey \\\n-H 'admin-store-token: morrison-hotel'\n```\n\n\u003e get all records from the store with a key prefix:\n```bash\ncurl http://localhost:8080/store?prefix=00 \\\n-H 'admin-store-token: morrison-hotel'\n```\n\n\u003e delete a specific record from the store:\n```bash\ncurl -X \"DELETE\" http://localhost:8080/store?key=002 \\\n-H 'admin-store-token: morrison-hotel'\n```\n\n\n## Generate Extism plug-in projects for Simplism\n\nYou can use **Simplism** to generate a project skeleton of an **Extism** plug-in with the following languages:\n\n- Golang\n- Rustlang\n- JavaScript\n\n### Generate a Golang project\n\n```bash\nsimplism generate golang hello my-projects\n```\nThis command will create this tree structure:\n```bash\nmy-projects\n└── hello\n   ├── build.sh\n   ├── Dockerfile\n   ├── go.mod\n   ├── main.go\n   ├── query.sh\n   ├── README.md\n   └── run.sh\n```\n\n### Generate a Rustlang project\n\n```bash\nsimplism generate rustlang hello my-projects\n```\nThis command will create this tree structure:\n```bash\nmy-projects\n└── hello\n   ├── build.sh\n   ├── Cargo.toml\n   ├── Dockerfile\n   ├── query.sh\n   ├── README.md\n   ├── run.sh\n   └── src\n      └── lib.rs\n```\n\n### Generate a JavaScript project\n\n```bash\nsimplism generate js hello my-projects\n```\nThis command will create this tree structure:\n```bash\nmy-projects\n└── hello\n   ├── build.sh\n   ├── Dockerfile\n   ├── index.d.ts\n   ├── index.js\n   ├── query.sh\n   ├── README.md\n   └── run.sh\n```\n\n✋ more languages to come\n\n## How is Simplism developed?\n\nSimplism is developed in Go with **[Wazero](https://wazero.io/)**[^1] as the Wasm runtime and **[Extism](https://extism.org/)**[^2], which offers a Wazero-based Go SDK and a Wasm plugin system.\n\n### Prerequisites\n\u003e 🚧 work in progress\n\nTo develop on the Simplism project and/or create Extism plug-ins, look at `.docker/compose/Dockerfile`, you will find the list of the necessary softwares, libraries, tools...\n\n### 👋 Or you can use ready to use environments\n\n[🍊 Open it with Gitpod](https://gitpod.io/#https://github.com/bots-garden/simplism)\n\n### Build Simplism\n\n```bash\ngo build\n./simplism version\n```\n\n### Write an Extism plug-in\n\n- Let's have a look at the official Extism documentation https://extism.org/docs/category/write-a-plug-in \n- Look into the `samples` directory of this repository:\n  ```bash\n  samples\n  ├── golang\n  │  ├── hello-plugin\n  │  └── simple-plugin\n  └── rustlang\n    ├── hello-plugin\n    └── simple-plugin\n  ```\n\n\u003e ✋ **important**: you can write Extism plug-ins with Go, Rust, AssemblyScript, Zig, C, Haskell and JavaScript\n\n\n[^1]: Wazero is a project from **[Tetrate](https://tetrate.io/)**\n[^2]: Extism is a project from **[Dylibso](https://dylibso.com/)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbots-garden%2Fsimplism","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbots-garden%2Fsimplism","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbots-garden%2Fsimplism/lists"}