aicoded.dev

aicoded dev: run apps on your computer

aicoded dev is the runner on your computer. It generates, builds and starts every app in a folder, signs viewers in as test personas, gives the apps their database, file stores, caught mail and outside services, rebuilds an app when its files change, and serves a dev UI with the apps' logs, traces and mail.

Running it

aicoded dev [dir]
aicoded dev --manual <app> [dir]

dir is the workspace, the current folder by default. aicoded dev takes every app below it:

Open the apps in Chrome. Firefox should work but is not tested. Safari does not work: it drops the persona cookie on plain http, and macOS does not resolve *.localhost.

dev.yaml

Local values and test personas live outside the repository, in dev.yaml in your user configuration folder: ~/.config/aicoded/dev.yaml on Linux ($XDG_CONFIG_HOME/aicoded/dev.yaml if that is set) and ~/Library/Application Support/aicoded/dev.yaml on macOS. It holds local secrets, so it must have mode 600 (E-DEV-001). Without the file, aicoded dev uses its defaults.

workspaces:
  /home/me/apps:              # absolute path of the folder you run aicoded dev in
    port: 8080                # the port of the apps and the dev UI; 8080 by default
    env: dev                  # the apps' environment: dev by default, or preview
    mysql: root:<password>@unix(/var/run/mysqld/mysqld.sock)/   # a local MySQL 8, for apps with sqldb
    personas:
      - {name: alice, roles: [staff], groups: [lisbon]}
      - {name: bob, roles: [staff, hr]}
    apps:
      people:
        settings: {team_address: team@acme.example}
        secrets: {partner_api_key: local-test-key}

Personas

On your computer, personas stand in for the company login. Choose one at http://<app>.localhost:8080/_aicoded/persona; a cookie keeps the choice. A persona's name is both the viewer's Subject and Name, with the persona's roles and groups, so it is 1 to 512 bytes, as a Subject is (E-DEV-021).

Without personas in dev.yaml, there are two: all-roles, with every role that the access and services sections of the workspace's apps name, and no-roles. The first persona of the list is the one a new browser gets.

Building blocks

Migrations

An app's tables come from its migrations, never from its code. Before it starts an app that declares sqldb, aicoded dev applies to the app's database, as the owner:

  1. the migrations the app published, which it asks the platform for with your sign-in and keeps in .aicoded/migrations.json. It asks at the app's first start, and again at a Start or Restart on the dev UI or the preview tool once its last answer is a minute old; a rebuild after a change takes the kept ones. When you are not signed in, or your sign-in cannot be read, it does not ask the platform: it prints one warning line, E-CLI-004: not signed in to the platform at <address>; only the draft is applied, or, with migrations kept there, applies them and says so. When the platform cannot be reached, it applies the ones kept there and prints one warning line, or, with none kept, only the draft. A .aicoded/migrations.json it cannot read is a warning line too, and only the draft is applied;
  2. then the statements of the draft, .aicoded/migration.sql, the next schema change.

The database's journal, the table aicoded_migrations, holds what ran. A draft that grows is applied on top. When the draft changes otherwise, or the journal holds steps that the published migrations and the draft do not start with, as after a publish, aicoded dev drops the app's dev database, makes it again and applies everything: its data is test data. A list of steps that aicoded dev cannot apply at all, such as one over 2000 steps or 1 MiB, stops the app with E-MIG-004 and leaves the database as it is. It never touches another app's database. A destructive statement of the draft (E-MIG-003) is applied like any other. A draft that aicoded check refuses (E-MIG-001, E-MIG-002, E-MIG-006) or a step that fails (E-MIG-005) stops the app, and its problems show at its address, on the dev UI and in what_broke.

The draft and .aicoded/migrations.json stay out of git: a new app's .gitignore lists both, and aicoded publish refuses a commit that holds the draft (E-MIG-001). aicoded publish sends the draft with the commit, and once that publish passed, deletes it and refreshes .aicoded/migrations.json; a publish that failed leaves the draft as it was. When you publish with --no-wait, or with the publish tool, aicoded status, release_status or the next publish does that once the publish has ended; release_status and the publish tool say what became of the draft in draft (sent, settled or none) and draft_note. A draft you changed after the publish was sent stays, to be cut down to what is still to publish. While the publish that carried the draft has not ended, aicoded publish and the publish tool refuse to send the draft again (E-MIG-001): wait for its outcome first.

aicoded check, when the workspace's dev.yaml (or that of a folder above it) names mysql:, makes a new test database for each app that declares sqldb; it reads dev.yaml only for the tests of such an app, and a dev.yaml it cannot use stops the whole check. It applies the same steps, runs the app's tests with AICODED_TEST_DB set to the data user's DSN, and drops the database and its users after. A test opens it with sqltest.Open(t) from aicoded.dev/framework/sqldb/sqltest, which skips the test when there is no test database.

Watching

aicoded dev watches the files of every app. When they change, it generates, builds and restarts that app; the files it writes itself start nothing. The running app keeps serving until the new one is built. A new app folder starts, and a removed one stops. An app you stopped on the dev UI is not rebuilt, and an app you run by hand is only generated.

When an app fails

An app that fails stops alone, and its address shows its problems, with code, file:line and fix, until a change builds or you start it again: Start or Restart on the dev UI, or the preview tool. It fails when it does not generate, holds a broken snapshot, does not build, lacks values in dev.yaml (E-DEV-003), has a draft that is refused or a migration that fails (E-MIG-001 to E-MIG-006), exits or is not ready within 30 seconds of starting (E-DEV-004), or gets a new name on its app: line while aicoded dev runs (E-DEV-015).

Only problems of the whole workspace stop aicoded dev:

What it keeps

Each app keeps its last 5000 log lines, 10000 spans and 1000 caught mails across restarts. Before it keeps or prints any of them, aicoded dev hides every value of the app's secrets that is 4 bytes or longer as [secret <name>]; it prints a warning for a shorter one.

The apps' data under aicoded dev is made up, so in environment dev the framework logs and traces each error with its text and each panic with its value, and an app that fails to start prints its whole error. Under env: preview and anywhere else it records only their kinds and codes, such as MySQL error 1062 (23000); see telemetry.

One aicoded dev runs per workspace. A second one for the same folder, a folder below it or a folder above it refuses and names the running one's address (E-DEV-012), then prints aicoded dev: log in to the running one at <link>, the login link of the running one's dev UI. See tools for the control socket they talk through.

The dev UI

aicoded dev serves a web UI for you, the developer, at http://localhost:8080 (the workspace's port, without an app name). Once it listens, before the apps build, it prints the login link: aicoded dev: the dev UI is at http://localhost:8080/_aicoded/login?token=<64 hex characters>.

Stop keeps an app stopped, also when its files change, until you press Start or Restart or call preview. Its address then answers 503: <app> is stopped. Start it on the dev UI at http://localhost:8080/apps/<app>, and the terminal shows aicoded dev: <app> stopped. Start restarts an app that runs. A new aicoded dev starts every app.

Running an app by hand

To run an app yourself, for example under a debugger, start aicoded dev --manual <app> [dir], with the flag before the folder and once for each such app, or press "Run it yourself" on the app's page. aicoded dev then keeps the app's runner up (its sockets, database, file stores and mail) in a run folder of mode 700, and never builds or starts the app. It prints the app's address line the first time, then the command that starts the app: aicoded dev: hello runs by hand; start it with: cd /path/to/hello && AICODED_RUNNER_DIR=<run folder> go run ..

See also

Markdown · Source on GitHub · framework f46741f