five/rag/04-idioms.md

doc, title, keywords, summary

doc	title	keywords	summary
five-idioms	Five web/worker app idioms (HTTP, Postgres, queue, LLM, build)	idioms cookbook http endpoint routing AP_JSONRESPONSE AP_BODY AP_GETPAIRS ctx_set ctx_get PG_QUERY PG_EXEC LABDB_GET_PG job queue FOR UPDATE SKIP LOCKED LLM_CHAT fnode build deploy	Battle-tested patterns from the production solmade app for building HTTP APIs and background workers in Five — endpoint skeleton, file-name routing, Postgres access, the DB job queue, LLM calls, and build/deploy.

Five idioms / cookbook

All snippets are from the real solmade app (/Users/charleskwon/solmade).

1. HTTP endpoint skeleton (use the shared helpers)

One FUNCTION Main() per .prg file under app/api/. Use the helpers in app/lib/api.prg instead of repeating PG/JSON/error boilerplate:

• REQUIRE_PG() → nPG — PG handle; on failure emits a 500 JSON error and returns -1.
• REQUIRE_JSON_BODY() → hBody | NIL — parsed JSON body; on failure emits 400, returns NIL.
• API_OK( [hPayload] ) → NIL — sends {"ok":true, ...payload}.
• API_ERR( nStatus, cMsg [, hExtra] ) → NIL — sends {"ok":false,"error":cMsg, ...}.

xBase can't force the caller to return, so the convention is "helper sets the response, caller returns immediately." API_OK/API_ERR return NIL so you can write RETURN API_ERR( 400, "…" ) on one line.

// POST /api/press-save.prg
FUNCTION Main()
   LOCAL nPG := REQUIRE_PG()
   LOCAL hBody, nUser

   IF nPG < 0
      RETURN NIL
   ENDIF

   hBody := REQUIRE_JSON_BODY()
   IF hBody == NIL
      RETURN NIL
   ENDIF

   nUser := Val( ctx_get( "auth_user_id", "0" ) )   // authed user (string → int)
   IF Empty( nUser )
      RETURN API_ERR( 401, "login required" )
   ENDIF

   RETURN API_OK( { "id" => 123 } )

STYLE: always write IF/FOR/WHILE bodies on their own indented lines. Do NOT use inline ; to pack multiple statements on one line (IF nPG < 0 ; RETURN NIL ; ENDIF is banned — it hurts visual review). The trailing-; line continuation (for long strings/SQL/args) is a different, allowed use.

Core verbs (used by/inside the helpers):

• AP_BODY() → raw request body (decode with hb_jsonDecode).
• AP_GETPAIRS( .t. ) → hash of query-string params (GET).
• AP_JSONRESPONSE( hHash ) → serialize + send JSON response.
• ctx_set( "status", N ) → set HTTP status code.
• ctx_get( "auth_user_id", "0" ) → authed user id (always a STRING; wrap in Val()). Also auth_email, auth_role, auth_display_name set by the auth middleware.

2. File-name routing

A URL path maps deterministically to a function (app/bridge_server.prg): strip /api/, drop .prg, replace -→_ and /→_, uppercase, append __MAIN.

/api/press-submit.prg   → PRESS_SUBMIT__MAIN   (Main() in app/api/press_submit.prg)
/api/auth/login.prg     → AUTH_LOGIN__MAIN

So: name the file with underscores, put a FUNCTION Main() in it, call it with hyphens.

3. PostgreSQL access

LOCAL nPG := LABDB_GET_PG()                  // pooled connection handle (opened at startup)

// SELECT → array of hashes. *** Column values come back as STRINGS. ***
LOCAL aRows := PG_QUERY( nPG, ;
   "SELECT id, title FROM articles WHERE status = $1 ORDER BY id DESC LIMIT 200", ;
   { "draft" } )
IF aRows == NIL ; aRows := {} ; ENDIF
LOCAL nId := Val( hb_CStr( aRows[1]["id"] ) )      // convert numeric columns explicitly

// non-SELECT
PG_EXEC( nPG, "UPDATE articles SET title=$1 WHERE id=$2", { "New", hb_NToS( nId ) } )

// INSERT ... RETURNING
aRows := PG_QUERY( nPG, ;
   "INSERT INTO articles (title) VALUES ($1) RETURNING id", { "Draft" } )
LOCAL nNew := aRows[1]["id"]

// error string
LOCAL cErr := PG_LAST_ERROR( nPG )

Idempotent schema, safe to call inside an endpoint:

FUNCTION ARTICLES_ENSURE( nPG )
   PG_EXEC( nPG, ;
      "CREATE TABLE IF NOT EXISTS articles ( "          + ;
      "  id SERIAL PRIMARY KEY, "                       + ;
      "  title TEXT NOT NULL DEFAULT '(제목 없음)', "    + ;
      "  created_at TIMESTAMPTZ NOT NULL DEFAULT now() " + ;
      ")" )
   RETURN NIL

4. DB job queue (avoid proxy timeout on long work)

Long LLM calls would blow the HTTP/proxy timeout. Pattern: submit → poll.

Submit (web) — insert queued, return id immediately:

aRows := PG_QUERY( nPG, ;
   "INSERT INTO text_tasks (kind, input, status, progress_msg, requested_by) " + ;
   "VALUES ('press', $1, 'queued', '대기 중', $2) RETURNING id", ;
   { cText, hb_NToS( nUser ) } )
AP_JSONRESPONSE( { "ok" => .t., "task_id" => aRows[1]["id"] } )

Worker (separate binary) — claim one row atomically; no two workers collide:

aClaim := PG_QUERY( nPG, ;
   "WITH n AS ( SELECT id FROM text_tasks WHERE status='queued' " + ;
   "            ORDER BY id FOR UPDATE SKIP LOCKED LIMIT 1 ) "    + ;
   "UPDATE text_tasks SET status='running', started_at=now() "    + ;
   "WHERE id=(SELECT id FROM n) RETURNING id, kind, input" )
IF aClaim == NIL .OR. Len( aClaim ) == 0
   RETURN .F.                                  // nothing queued; caller sleeps
ENDIF
// ... do work, periodically UPDATE progress_pct/progress_msg ...
PG_EXEC( nPG, "UPDATE text_tasks SET status='done', progress_pct=100, " + ;
   "result=$1, finished_at=now() WHERE id=$2", { cOut, hb_NToS( nId ) } )

Status (web) — client polls SELECT status, progress_pct, progress_msg, result. Run multiple worker processes for concurrency; SKIP LOCKED keeps them race-free.

5. LLM calls

LLM_CHAT(cSystem, cUser, hOpts) → { "ok"=>.T./.F., "text"=>cResult, "error"=>cMsg }.

LOCAL hRes := LLM_CHAT( PRESSER_SYSTEM_PROMPT(), cUser, ;
   { "temperature" => 0.5, "max_tokens" => 4000 } )
IF hb_HGetDef( hRes, "ok", .f. )
   cOut := hb_HGetDef( hRes, "text", "" )
ELSE
   // hRes["error"]  — endpoint unreachable / HTTP != 200 / empty response
ENDIF

Endpoint resolves from SOLMADE_LLM_URL env (OpenAI-compatible /v1); model name is auto-resolved (a literal "local" is replaced by the actually-loaded model id, because mlx/llama servers reject unknown model names). <think>...</think> is stripped.

6. Build & deploy (fnode)

Web and worker are separate binaries built from explicit file lists.

# build.sh — web
"$FNODE" build \
  app/bridge_server.prg app/auth/*.prg app/lib/*.prg app/api/*.prg "$BRIDGE"/*.prg \
  --rtl fivenode_go/hbrtl_ext/pgrtl \
  --rtl fivenode_go/hbrtl_ext/httpserver \
  --go-replace gitea.fivego.org/kwon_ai/solmade="$SOLMADE_ROOT" \
  --module gitea.fivego.org/kwon_ai/solmade/_solmade_web \
  -o solmade-web

• --rtl <pkg> blank-imports a Go package whose init() registers RTL functions (e.g. pgrtl provides PG_QUERY/PG_EXEC; httpserver the web bridge).
• --go-replace pkg=path resolves a private module without a proxy.
• --module <name> sets the temp module path (must sit under the app's module so RTL packages can import the app's internal packages).

Quality gates (lint + smoke)

Two committed gates keep a dynamically-typed PRG codebase honest (solmade):

• lint.sh — static checks: bans inline ; statement separators (IF x ; y ; ENDIF — hurts visual review; trailing-; continuation is fine) and flags user input concatenated into SQL instead of $1 binds. Exit 1 on any ERROR. Fast, no server/DB needed.
• smoke_test.sh — runtime endpoint contract test (below).

Wiring: build.sh runs ./lint.sh first and aborts the build on violation; a .githooks/pre-commit runs it on every commit (enable once with git config core.hooksPath .githooks; bypass with git commit --no-verify). Run smoke_test.sh at deploy time (it needs the server up), not in the hook.

Safety net: endpoint smoke test

Dynamic typing has no compile-time guarantee, so a smoke test is the practical safety net (buy it back at runtime, like Python+pytest). solmade ships smoke_test.sh: it mints a temp superadmin session in PG, curls each endpoint, and asserts HTTP status + the JSON ok/shape contract (./smoke_test.sh fast; --full adds the queue→worker→LLM E2E), exiting non-zero on any failure. Run it after any refactor.

Deploy (launchd): launchctl kickstart -k gui/$(id -u)/kr.solmade.web (and ...worker1/2/3). The worker build (build_worker.sh) links cmd_prg/job_worker.prg plus the shared app/lib/*.prg (so LLM_CHAT and prompts are available to it too).

7. Reaching the ecosystem — two paths (pick by runtime)

There are two distinct ways to use the outside world from PRG; they belong to different runtimes (see five-overview):

(a) Go RTL — fivenode_go (single Go binary, NO Node). Wrap a Go package in a thin hbrtl_ext module, blank-import it with --rtl, call the registered function. This is the production path (solmade): no runtime deps, one binary. Use for anything with a good Go library (Postgres, PDF, XLSX, crypto/rand, argon2, bluemonday).

(b) Node Require() — original fivenode (Node.js + N-API/koffi). PRG calls an npm package directly, Node-style, with no wrapper to write:

oQR := Require( "qrcode" )                      // npm package
cSvg := aWait( oQR:toString( cUrl, { "type" => "svg" } ) )   // async → aWait()
oQR:__end__()                                   // release the handle

oId := Require( "crypto" ):randomUUID()         // Node builtin, sync
oOs := Require( "os" )                          // builtins: os, path, fs, ...
cHost := oOs:hostname() ; oOs:__end__()

• Sync npm: obj:methodSync(...) (e.g. qr-image imageSync). Async (Promise): wrap the call in aWait(...). Always obj:__end__() when done.
• Pass PRG hashes as JS objects: { "width" => 240, "color" => { "dark" => "#000" } }.
• The server allowlists each handler — register new ones in napi/test/server.js (allowedPrg.add('/api/foo.prg')).

When to choose (b): the npm package has no good Go equivalent, or reimplementing it would be heavy (QR codes, charting, specialized parsers, ML/JS-only SDKs). You get the entire npm registry with zero glue code — the cost is a Node runtime instead of a single static binary. Example: napi/test/api/sharekit.prg composes npm qrcode + Node crypto/os in one PRG to build an article share kit (QR svg+png + tracking UUID).