Skip to content

Organise the API into domain directories with explicit exports - #69

Merged
Mistium merged 8 commits into
mainfrom
src-layout
Nov 1, 2026
Merged

Mistium merged 8 commits into
mainfrom
src-layout

Conversation

@Mistium

@Mistium Mistium commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

Stacked on #68. Merge MistWarp/docs#18 alongside it: the README now links to the Backend section that PR adds.

The API was 140 files at the repo root sharing one namespace: 1,418 functions and 463 globals, each file imported into main.osl in an order that mattered, and every route in one 600-line list. It's now organised by domain:

main.osl        imports the domains, runs startup and migrations, registers routes, starts the server (722 → ~170 lines)
src/
  config/ core/ http/ auth/ storage/ projects/ history/ git/
  games/ realtime/ community/ admin/ classroom/ rotur/
  • Explicit public surfaces. Each file has an export {...} block listing what other directories use: 491 of 1,605 top-level names. The rest are private.
  • Routes live with their domain. Each directory registers its own in routes.osl (registerProjectRoutes(api) and so on), and main.osl calls them in the same order as before.
  • Caches sit next to the code that uses them, and tests beside the files they test.
  • History is kept. Every file moved with git mv in a commit of its own, so git log --follow works.

Tooling

  • opal.json holds the usual commands.
  • CI (.github/workflows/test.yml) type-checks, tests, compiles and runs the smoke test on every PR, with OSL pinned to a commit and built from a clone.
  • scripts/route_dump.py prints every route with its middleware.
  • scripts/check_conventions.py rejects code comments and em dashes in added lines. A linter written in OSL will replace it in a follow-up.

Docs. The README is now an overview. Its 250 lines of reference material moved to the Backend section of the docs (MistWarp/docs#18). AGENTS.md tells coding agents the layout, the /v1 contract, the OSL 3.0 traps and the checks.

Behaviour is unchanged

  • The route dump finds 634 routes, each with its middleware chain and method order, identical before and after.
  • osl test passes 45/45.
  • The smoke responses match between main (old compiler), Build on OSL 3.0 #68 and this branch.
  • Startup order was compared from the generated Go: config now runs first, and every other file's top-level code only reads config, creates caches or defines constants.

An independent review confirmed it's a pure move and checked the startup order, the deploy layout (compiling from the repo root, build.sh, go.mod, native/, relative data/ paths) and CI. Its findings are addressed.

There is no visible change.

@Mistium
Mistium changed the base branch from main to osl3-migration November 1, 2026 03:37
scripts/route_dump.py follows main.osl's router setup through the route
functions and prints each route with its middleware chain, sorted, plus
the method order per path, so a reorganisation can be diffed.
A pure git mv so history follows each file. Imports are fixed in the next commit.
main.osl now composes the app: it imports each src/<domain> directory,
runs startup, builds the router and calls one register function per
domain. Configuration moves to src/config, each global cache moves next
to the code that uses it, and each domain's routes move to its own
routes.osl in their original order, with the same paths, methods,
middleware and limits. opal.json marks the project root so tests can
import across directories. r2Client is declared as *s3.Client because an
auto global loses its type in other files.
Each file now exports only the names that code in another directory,
main.osl or a test elsewhere uses. Everything else is private to its
directory, so main.osl can only reach a domain through that surface.
The README describes the src/<domain> layout and the check, test, build,
route dump and smoke commands. The workflow installs OSL 3.0, type checks,
runs the tests, compiles and runs the smoke test, which now fails on any
server error.
…ke the README an overview

CI now builds OSL from a fixed commit instead of whatever main is, so a compiler change
can't turn it red or test against a different compiler than production.

The smoke test seeds an agreement, so accepting it is exercised instead of returning 400,
and it now unshares the project before deleting it, checking both the refusal and the
delete.

The README's reference material moved to the Backend section of the MistWarp docs.
scripts/check_conventions.py rejects code comments and em dashes in added lines of OSL and
Python files, with a scanner that ignores // inside strings. It runs in CI on pull requests
and as opal's conventions script.

AGENTS.md covers the src/<domain> layout, the /v1 contract and the tools that guard it, the
OSL 3.0 traps that changed behaviour in this migration, and the checks to run.
…opal.json

git.rotur.dev answers 500 for archive downloads, so CI clones OSL and checks out the pinned
commit instead.

The conventions check uses Python's tokenize for Python files, so trailing comments are
caught and # inside strings is not, and it scans Go files too. Like the JavaScript check, it
compares comment text against removed lines, so editing a line with an existing comment
does not flag it.

opal.json keeps its original formatting.
@Mistium
Mistium changed the base branch from osl3-migration to main November 1, 2026 07:17
@Mistium
Mistium merged commit a482877 into main Nov 1, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant