shsf/shsf-cli
2
0
Fork 0
Code Issues Pull Requests Actions Releases 2 Wiki Activity

Added coding docs from shsf to shsf-cli

Browse Source
This commit is contained in:
Space-Banane
2026-04-14 18:23:11 +02:00
parent d9d6871f09
commit c912c791fa
1 changed files with 275 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
OpenclawSkill.md
+274
View File
@@ -113,3 +113,277 @@ and then replace the old one with the new one using `mv`.
## Missing a feature? ## Missing a feature?
Features might be not documented yet, as this skill document rarely updates. Features might be not documented yet, as this skill document rarely updates.
Use the shsf -h command to see options and features. Use the shsf -h command to see options and features.
CODING DOC:
# SHSF Platform Reference (Agent-Optimized)
## Critical Rules (check before writing any code)
- Python files use `.py`, Go files use `.go` — never mix runtimes
- Go package must be `main`; entry-point must be `main_user()`, never `main()`
- Python entry-point must be `def main(args):`
- **Always** `import json` and call `json.loads(args.get("body", "{}"))` before accessing body fields in Python
- Forbidden filenames: `_runner.py`, `_runner.js`, `init.sh`
- Filenames must never contain `/` or `\` — no subdirectories
- Never hard-code secrets — use environment variables via `os.getenv()`
- Never invent SHSF APIs not documented here
- Never write partial files or placeholder comments
- Only create `requirements.txt` / `go.mod` if dependencies are actually needed
---
## Entry Points
### Python
```python
def main(args):
return {"hello": "world"} # plain dict → 200 JSON
```
### Go
```go
package main
func main_user(args interface{}) (interface{}, error) {
return map[string]string{"hello": "world"}, nil
}
```
---
## The `args` Object
| Field | Type | Notes |
|------------|------------|-----------------------------------------------------------------------|
| `body` | string | Raw JSON string — **must** be parsed with `json.loads()` before use |
| `queries` | dict / map | URL query parameters |
| `route` | string | Sub-path segment after function URL. Default: `"default"` |
| `headers` | dict / map | Lowercased HTTP request headers |
| `raw_body` | bytes | Raw request body (file uploads, binary data) |
| `method` | string | HTTP method (GET, POST, …) |
Always use `.get()` / nil-checks — never assume a field is present.
### Python args example
```python
import json
def main(args):
body = json.loads(args.get("body", "{}")) # always parse first
queries = args.get("queries", {})
route = args.get("route", "default")
name = body.get("name", "stranger")
page = queries.get("page", "1")
return {"greeting": f"Hello {name}", "page": page, "route": route}
```
---
## Response Formats
### Simple 200 JSON (plain dict)
```python
return {"key": "value"}
```
### v2 Envelope (control status, headers, body)
```python
return {
"_shsf": "v2",
"_code": 201, # HTTP status code
"_headers": {"Content-Type": "application/json"}, # optional
"_res": {"created": True, "id": 42} # response body
}
```
### Error response
```python
return {"_shsf": "v2", "_code": 400, "_res": {"error": "missing field 'name'"}}
```
### Redirect (301 / 302)
```python
return {"_shsf": "v2", "_code": 302, "_location": "https://example.com/target"}
```
### HTML response
```python
def main(args):
with open("index.html", "r") as f:
html = f.read()
return {"_shsf": "v2", "_code": 200, "_headers": {"Content-Type": "text/html"}, "_res": html}
```
> **Static HTML shortcut**: if the only file is a single `.html` set as the startup file, SHSF serves it directly without spinning up a runtime.
---
## Routing
`args["route"]` holds the single URL segment after the function base URL (no leading slash, default `"default"`). Only **one** segment is supported.
```python
def main(args):
route = args.get("route", "default")
if route == "register": return handle_register(args)
elif route == "login": return handle_login(args)
elif route == "status": return {"status": "ok"}
else: return {"_shsf": "v2", "_code": 404, "_res": {"error": "route not found"}}
```
---
## Environment Variables
Never hard-code secrets. Define them in the SHSF dashboard.
```python
import os
def main(args):
api_key = os.getenv("MY_API_KEY", "")
if not api_key:
return {"_shsf": "v2", "_code": 500, "_res": {"error": "MY_API_KEY not set"}}
return {"ok": True}
```
Go: `apiKey := os.Getenv("MY_API_KEY")`
---
## Persistent Storage
| Path | Persistence | Use for |
|---------|--------------------------|---------------------------------|
| `/app/` | Persists across calls | Cache, state files |
| `/tmp/` | Wiped on container restart | Truly temporary scratch work |
**WARNING**: SHSF may restart or update containers, which recreates all of it, even the `/app/` directory. For critical data, use `_db_com` instead.
```python
import json, os
CACHE = "/app/cache.json"
def main(args):
data = json.load(open(CACHE)) if os.path.exists(CACHE) else {}
data["hits"] = data.get("hits", 0) + 1
json.dump(data, open(CACHE, "w"))
return {"hits": data["hits"]}
```
### Redis (shared key-value, fast)
```python
import redis
r = redis.Redis(host="localhost", port=6379, db=0)
def main(args):
r.incr("counter")
return {"counter": int(r.get("counter"))}
```
---
## Database (`_db_com`) — Python
`_db_com.py` is auto-provisioned. Add `requests` to `requirements.txt`.
```python
from _db_com import database
from datetime import datetime, timedelta
db = database()
def main(args):
db.create_storage("my_app", purpose="application data") # idempotent, safe every call
db.set("my_app", "username", "alice") # write
expires = (datetime.utcnow() + timedelta(hours=1)).isoformat()
db.set("my_app", "session", "tok_abc", expires_at=expires) # write with TTL
username = db.get("my_app", "username") # read (None if missing)
exists = db.exists("my_app", "username") # existence check
items = db.list_items("my_app") # list all keys
db.delete_item("my_app", "username") # delete
return {"username": username, "items": items}
```
### Go `dbcom`
```go
package main
import "myfunction/dbcom"
func main_user(args interface{}) (interface{}, error) {
db := dbcom.New()
if _, err := db.Set("my-storage", "key", "value", nil); err != nil {
return nil, err
}
value, err := db.Get("my-storage", "key")
if err != nil {
return nil, err
}
return map[string]interface{}{"value": value}, nil
}
```
---
## File Uploads / Raw Body
```python
def main(args):
raw = args.get("raw_body")
if raw is None:
return {"_shsf": "v2", "_code": 400, "_res": {"error": "no body provided"}}
if isinstance(raw, str):
raw = raw.encode("latin-1")
with open("/app/upload.bin", "wb") as f:
f.write(raw)
return {"_shsf": "v2", "_code": 200, "_res": {"saved": True}}
```
---
## Secure Header (`x-secure-header`)
When the secure-header feature is enabled, SHSF validates the token **before** invoking your function — no need to re-validate. Read it only for logging:
```python
def main(args):
token = args.get("headers", {}).get("x-secure-header", "")
return {"authenticated": True, "token_preview": token[:4] + "…"}
```
---
## Dependency Files
| Runtime | File | Notes |
|---------|-------------------|------------------------------------------------|
| Python | `requirements.txt`| pip-installed before first run |
| Go | `go.mod`+`go.sum` | Module deps, auto-downloaded |
Only create these files if you have actual dependencies.
### Python `requirements.txt`
```
requests==2.31.0
beautifulsoup4==4.12.2
```
### Go `go.mod`
```
module myfunction
go 1.23
require (
github.com/google/uuid v1.3.0
)
```
Supported Go versions: `1.20`, `1.21`, `1.22`, `1.23`