Proposal: front-end-owned machine-readable integration contract #852

Activity

1. 0xShug0 commented on Oct 13, 2026

   

   0xShug0

   on Oct 13, 2026

   Owner

   More actions

   @lapy Thanks! This is generally useful, but please hold for now. A few more refactors are underway. Once they're done, I'll check how this fits into the codebase and ping you.
2. lapy commented on Oct 13, 2026

   

   lapy

   on Oct 13, 2026

   ContributorAuthor

   More actions

   Hi @0xShug0, of course! No rush :)
   Thanks for considering it and for the great work you’re doing with Audio.cpp.

   👍React with 👍1Reacted by 0xShug0
3. supomarlo commented on Oct 23, 2026

   

   supomarlo

   on Oct 23, 2026

   Contributor

   More actions

   This direction would help downstream clients like mine.

   I maintain a desktop client for audio.cpp. It does not bundle the server; users point
   it at their own copy, so versions vary, including third-party builds.

   A smaller related need: exposing the server version over HTTP (e.g. in GET /health)
   would be useful. Model support and interfaces differ between versions, and the client
   needs to know which version it is talking to.

   --version is the only programmatic source today, and it is not reliable for me. Some
   servers were started outside the app, so I cannot reliably query the binary that
   launched them. Some third-party builds do not produce a parseable version string. In
   both cases, version detection becomes cumbersome and fragile.

   👀React with 👀1Reacted by 0xShug0
4. chenhz01 commented on Nov 2, 2026

   

   chenhz01

   on Nov 2, 2026

   More actions

   The hold makes sense mid-refactor — one small thing for whenever this lands: supomarlo's /health version point composes naturally with the contract idea, since a published contract already needs a version field to be meaningful. To make the shape testable before any routes get frozen, here's a validator for the server-owned surface:

   """Validate a front-end-owned integration contract (issue #852 direction).
   Usage: python contract_lint.py contract.json
   Checks the fields the server should publish: semver, routes with request/
   response encodings, errors, stream events, plus an independent CLI surface.
   """
   import json, sys
   
   REQUIRED_SERVER = ["version", "routes", "errors", "stream_events"]
   REQUIRED_ROUTE = ["path", "method", "request", "response"]
   VERBS = ("GET", "POST", "PUT", "DELETE", "PATCH")
   
   def err(msgs, path, msg):
       msgs.append("%s: %s" % (path, msg))
   
   def check_routes(spec, msgs):
       if not spec.get("routes"):
           err(msgs, "routes", "empty - clients would hardcode again")
       for i, r in enumerate(spec.get("routes", [])):
           for k in REQUIRED_ROUTE:
               if k not in r:
                   err(msgs, "routes[%d]" % i, "missing '%s'" % k)
           if r.get("method") not in VERBS:
               err(msgs, "routes[%d].method" % i, "unknown verb")
   
   def check_version(spec, msgs):
       v = str(spec.get("version", ""))
       parts = v.split(".")
       if len(parts) != 3 or not all(p.isdigit() for p in parts):
           err(msgs, "version", "'%s' is not semver" % (v or "missing"))
   
   def main():
       if len(sys.argv) != 2:
           sys.exit("usage: contract_lint.py <contract.json>")
       spec = json.load(open(sys.argv[1], encoding="utf-8"))
       msgs = []
       check_version(spec, msgs)
       check_routes(spec, msgs)
       for k in REQUIRED_SERVER:
           if k not in spec:
               err(msgs, "root", "missing '%s'" % k)
       cli = spec.get("cli")
       if not isinstance(cli, dict) or not cli.get("invocations"):
           err(msgs, "cli", "CLI surface missing - owned independently of server")
       if msgs:
           print("CONTRACT INVALID (%d problems)" % len(msgs))
           for m in msgs:
               print(" -", m)
           return 1
       print("CONTRACT OK: %s - %d routes, %d stream events, CLI surface present"
             % (spec.get("version"), len(spec["routes"]), len(spec["stream_events"])))
       return 0
   
   if __name__ == "__main__":
       sys.exit(main())

   It checks the fields the thread agrees the server should own — semver, routes with request/response encodings, errors, stream events — plus an independently-owned CLI block. Run it against a draft contract.json during the refactors and whatever survives is the schema worth publishing. Happy to draft the schema spec and this linter as a PR whenever you're ready.