Skip to content

AGENTS.md

Latest commit

 

History

History
201 lines (164 loc) · 10.5 KB

AGENTS.md

File metadata and controls

201 lines (164 loc) · 10.5 KB
Raw

AGENTS.md - LSP Examples

Purpose

This repository contains independent Barracuda App Server (BAS) examples. BAS is the embedded web/application server C code library used by Mako Server, Xedge, and Xedge32. LSP means Lua Server Pages.

Use this file as the repository-level baseline. If the selected example has its own AGENTS.md, that file is more specific and must be read before editing.

First Steps

  • Identify the exact example, subexample, and runnable app root before changing files.
  • Identify the target runtime: Mako Server, Xedge, Xedge32, or more than one. Do not assume runtime-specific APIs or lifecycle behavior are interchangeable.
  • Read the selected example's README.md first; it is the run and verification contract.
  • Read any local AGENTS.md, design note, or skill file named by the README or local AGENTS file.
  • Inspect the existing app shape and follow its conventions before introducing new routing, state, or transport patterns.
  • Modify only the selected example unless the user explicitly asks for cross-example parity.
  • Keep the common example shape when adding or moving app files: root README.md, runnable app files under www/ or the variant directory named by the local README.

Source Of Truth

Do not invent BAS, Lua, LSP, SMQ, Mako, Xedge, Xedge32, or OPC UA APIs. Use the official documentation for exact names, signatures, and behavior.

This AGENTS.md may be copied standalone into other work directories. Treat the local paths below as relative to the directory containing this file.

When this file references a public BAS document or AI skill, resolve it in this order:

  1. A same-directory file with the referenced filename.
  2. ./.agents/reference/rtl/ relative to this file or project.
  3. The listed public source URL.

If a referenced file is missing and network access is available, download it from the public URL and save it under ./.agents/reference/rtl/. Record the source URL and download date in ./.agents/reference/rtl/manifest.md or in a short header at the top of the cached file.

Use local copies for normal work. Re-fetch only when the user asks for current/latest guidance, the local copy is missing, or the local copy conflicts with observed API/runtime behavior.

For fully offline use, copy this AGENTS.md together with the ./.agents/reference/rtl/ directory.

Reference Local copy Source URL
BAS API bundle ./.agents/reference/rtl/basapi.md https://realtimelogic.com/downloads/basapi.md
Xedge32 and ESP32 API reference ./.agents/reference/rtl/esp32api.md https://realtimelogic.com/downloads/esp32api.md
OPC UA API reference ./.agents/reference/rtl/opcuaapi.md https://realtimelogic.com/downloads/opcuaapi.md

Reference priority:

  1. basapi.md for BAS API syntax, signatures, and behavior.
  2. esp32api.md for Xedge32 and ESP32-specific APIs.
  3. opcuaapi.md for OPC UA APIs.

If an example or AI skill conflicts with the relevant API reference, trust the API reference and fix the local guidance.

Optional Public Skills

Load only the smallest skill set that matches the task:

Skill Local copy Source URL
VFS and routing ./.agents/reference/rtl/VFS-skill.md https://realtimelogic.com/downloads/ai-skills/VFS-skill.md
Authentication and authorization ./.agents/reference/rtl/Authentication-Authorization-Skill.md https://realtimelogic.com/downloads/ai-skills/Authentication-Authorization-Skill.md
General web/application security ./.agents/reference/rtl/OWASP-General-Security-Skill.md https://realtimelogic.com/downloads/ai-skills/OWASP-General-Security-Skill.md
SMQ real-time messaging ./.agents/reference/rtl/SMQ-Skill.md https://realtimelogic.com/downloads/ai-skills/SMQ-Skill.md
SQLite write serialization ./.agents/reference/rtl/SQLite-Skill.md https://realtimelogic.com/downloads/ai-skills/SQLite-Skill.md
Lua/C/C++ bindings ./.agents/reference/rtl/Lua-Binding-Skill.md https://realtimelogic.com/downloads/ai-skills/Lua-Binding-Skill.md
Mako Server service deployment ./.agents/reference/rtl/Deploy-Mako-Server-Skill.md https://realtimelogic.com/downloads/ai-skills/Deploy-Mako-Server-Skill.md
LSP browser interfaces ./.agents/reference/rtl/Build-LSP-Web-Interfaces-Skill.md https://realtimelogic.com/downloads/ai-skills/Build-LSP-Web-Interfaces-Skill.md

Selection rules:

  • Start with VFS for URL layout, resource readers, directory callbacks, static trees, hidden resources, REST-style paths, WebDAV, or WFS.
  • Add authentication for identity, sessions, roles, method/path permissions, or protected subtrees. Use it with VFS when deciding where protection is mounted.
  • Add OWASP security for public exposure, production readiness, untrusted input, uploads, CORS, cookies, TLS, secrets, or code review. It complements, but does not replace, the API reference.
  • Use SQLite before designing any request path that writes to SQLite.
  • Use SMQ for publish/subscribe, browser/device messaging, presence, discovery, one-to-one messages, or synchronized clients. Use language-specific references for low-level non-Lua client implementation.
  • Use Lua bindings only for native C/C++ integration, including ba.* modules, ba.create.* factories, IoIntf, request/response helpers, or HttpDir-derived objects exposed to Lua.
  • Use Mako deployment for service/daemon installation, VPS operation, boot-time startup, unattended logging, or ACME operations.
  • Use LSP web interfaces when choosing among server-rendered pages, htmx, Fetch/JSON, WebSocket RPC, and SMQ-driven browser interaction.

Common combinations:

Task Skills
Protected REST or admin subtree VFS + authentication + OWASP
Database-backed browser form/API LSP web interfaces + SQLite + OWASP
Live browser/device dashboard LSP web interfaces + SMQ; add authentication/OWASP when exposed
Production Mako service Mako deployment; add authentication/OWASP for remotely reachable management
Native sensor or protocol API Lua bindings + the relevant runtime API; add VFS or SMQ only for its exposed interface

Runtime And Application Model

  • Put application startup state, persistent clients, timers, shared helpers, and other app-lifetime resources in .preload or modules loaded by .preload.
  • Provide onunload() whenever an application or .xlua program owns resources that require deterministic cleanup, such as sockets, timers, threads, database connections, mounts, or hardware handles.
  • In Xedge applications, use .xlua for independent background programs such as protocol clients, hardware logic, and long-running IoT tasks. Use LSP for browser-facing request/response work. Confirm Xedge32-specific behavior in esp32api.md.
  • Xedge .xlua environments inherit from the application's .preload environment. LSP pages can access application state through app, but do not inherit .preload variables as ordinary globals.
  • Treat the application resource reader's dir and I/O object as runtime-owned application objects. Use the VFS and API references before mounting, unlinking, filtering, or changing response headers.

Use the correct state scope:

Scope Lifetime and visibility Appropriate use
Request command environment One request Request parsing, response generation, request-local values
page Lifetime of one LSP resource; shared by all users of that page Per-page caches or counters, never per-user secrets
app Lifetime of one application/resource reader; shared by its pages Configuration, shared helpers, caches, timers, persistent clients
Session One authenticated/browser session Per-user state
_G Entire Lua state; may cross apps, pages, requests, and sessions Deliberate process-global facilities only

Do not store user-specific data in page, app, or _G. Do not use _G as a shortcut for ordinary application state.

BAS Coding Rules

  • Keep server-side Lua/LSP responsible for data sources, device/runtime logic, authorization, validation, and HTTP/SMQ endpoints.
  • Keep browser JavaScript responsible for rendering and user interaction. Do not embed server secrets in client code.
  • Define each HTTP or message contract before implementation: method/topic, inputs, validation, response/payload type, errors, authorization, timeouts, and retry/idempotency behavior.
  • Validate all external input on the server, including URL data, forms, JSON, headers, uploads, WebSocket frames, SMQ messages, and device data.
  • Keep request handlers bounded. Move app-lifetime or background work to the runtime mechanism designed for it rather than retaining request objects or blocking a request indefinitely.
  • Serialize SQLite writes through the dedicated writer pattern.
  • Keep hidden application files such as .preload, modules, databases, keys, and configuration out of public URL space.
  • Prefer BAS-native APIs and the existing example pattern over third-party frameworks.
  • Keep changes small and runtime-specific unless the example explicitly supports multiple runtimes.

Verification

There is no single command for the whole repository. Run and test the selected example exactly as documented in its README, commonly:

cd path/to/example
mako -l::www

Verify in proportion to the changed lifecycle:

  • After changing .preload, restart or reload the application and inspect startup and unload behavior; a browser refresh alone is not sufficient.
  • After changing .xlua, verify activation, trace output, replacement of the previous program, and deterministic cleanup of owned resources.
  • For LSP and HTTP APIs, verify method, status, content type, response body, validation failures, authorization failures, and side effects.
  • For browser UI changes, exercise initial load, direct navigation, form or fragment updates, browser console errors, and at least one failure path.
  • For WebSocket or SMQ endpoints, use the intended client handshake and message flow. A plain HTTP request to an endpoint such as smq.lsp is not a valid protocol test.
  • For real-time shared state, use at least two clients and test disconnect and reconnect behavior.
  • For service/deployment changes, verify foreground startup first, then service identity, paths, listeners, logs, stop/start, restart policy, and boot startup.

Inspect runtime trace/log output after actions expected to execute Lua. A file write or successful start command proves only that the runtime accepted the operation, not that the application executed correctly.