Documentation
¶
Overview ¶
Package dev is the local runner behind aicoded dev: it builds an app, serves the runner protocol to it through the runner server, and fronts it with a gateway that stands in for the company login. Its Runner serves the runner protocol alone, to one app that another program starts.
Index ¶
- func DefaultPersonas(ms ...manifest.Manifest) []devconfig.Persona
- func FindRunning(ctx context.Context, dir string) (root, socket string, ok bool)
- func Platform() migrations.Platform
- func Run(ctx context.Context, dir string, out io.Writer, opts Options) error
- func RunWorkspace(ctx context.Context, root string, ws devconfig.Workspace, state string, ...) error
- func RunningLogin(ctx context.Context, dir string) (string, bool)
- func Skip(rel string) bool
- func StateDir(root string) (string, error)
- func StatePath(root string) (string, error)
- type Config
- type Gateway
- func (g *Gateway) Add(name, socketPath string, st *store)
- func (g *Gateway) AddManual(name, socketPath, command string)
- func (g *Gateway) Fail(name string, ps []problem.Problem)
- func (g *Gateway) Personas() []devconfig.Persona
- func (g *Gateway) Remove(name string)
- func (g *Gateway) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (g *Gateway) Starting(name string)
- func (g *Gateway) Stopped(name string)
- type Instance
- type MySQLAdmin
- type Options
- type Ring
- type Runner
- type RunnerOptions
- type Services
- type Signer
- type Users
- type Workspace
- func (w *Workspace) Changed() <-chan struct{}
- func (w *Workspace) Close()
- func (w *Workspace) Logs(_ context.Context, q devapi.LogQuery) ([]devapi.LogEntry, error)
- func (w *Workspace) Mail(_ context.Context, app string) ([]devapi.MailSummary, error)
- func (w *Workspace) MailGet(_ context.Context, app, id string) (devapi.Mail, error)
- func (w *Workspace) MailReceive(_ context.Context, app string, m devapi.InboundMail) (string, error)
- func (w *Workspace) Personas() []devconfig.Persona
- func (w *Workspace) Rescan(ctx context.Context)
- func (w *Workspace) Restart(_ context.Context, app string) (devapi.App, error)
- func (w *Workspace) SetManual(app string, on bool) error
- func (w *Workspace) Start(app string) error
- func (w *Workspace) Status(context.Context) (devapi.Status, error)
- func (w *Workspace) Stop(app string) error
- func (w *Workspace) Trace(_ context.Context, id string) (devapi.Trace, error)
- func (w *Workspace) Traces(_ context.Context, q devapi.TraceQuery) ([]devapi.TraceSummary, error)
- func (w *Workspace) WhatBroke(_ context.Context, app string) (devapi.Broken, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultPersonas ¶
DefaultPersonas are the personas of a workspace whose dev.yaml names none: one with every role the apps' pages and functions ask for, and one with no role.
func FindRunning ¶
FindRunning returns the root and control socket of an aicoded dev that runs for dir or a folder above it. One that answers with another control protocol counts as running.
func Platform ¶
func Platform() migrations.Platform
Platform returns the client of the platform that AICODED_PLATFORM names, which gives the migrations the apps published with the builder's sign-in. When AICODED_PLATFORM is not valid, asking it fails with that error.
func Run ¶
Run serves every app under dir on the local runner until ctx is done, as Host does, and prints the same lines. It refuses a dir with no app before it reads dev.yaml.
func RunWorkspace ¶
func RunWorkspace(ctx context.Context, root string, ws devconfig.Workspace, state string, out io.Writer) error
RunWorkspace serves every app under root until ctx is done, with the workspace settings ws and the private state folder state, an absolute path. It returns only a problem of the whole workspace, as Open does; an app that fails stops only itself.
func RunningLogin ¶
RunningLogin returns the login link of the dev UI of the aicoded dev that Host refuses dir for, with E-DEV-012. It reads the token from that aicoded dev's state folder, and reports false when none runs or its token cannot be read.
func Skip ¶
Skip reports whether aicoded dev ignores the folder rel under a workspace root: a folder whose name starts with . or _, other than .aicoded, vendor, node_modules, testdata and the assets aicoded generate writes, pages/assets_gen.
Types ¶
type Config ¶
type Config struct {
// Root is the workspace's folder and State its private state folder, both absolute.
Root, State string
// Dev holds the workspace's settings from dev.yaml. Open reads its port, environment,
// personas and MySQL server once; port 0 picks a free port, and no environment is dev.
Dev devconfig.Workspace
// Values returns the dev.yaml values of app at every start of it; nil uses Dev.Apps.
Values func(app string) (devconfig.AppValues, error)
// Out gets the lines aicoded dev prints and the output of the apps.
Out io.Writer
// Watch rebuilds an app when its files change, and starts and stops apps as their
// aicoded.yaml appears and goes.
Watch bool
// Manual names the apps the developer runs by hand: aicoded dev keeps their runners up and
// never builds or starts them.
Manual []string
// Login prints the login link of the dev UI, which holds its access token. Without it, the
// line names only the dev UI's address.
Login bool
// Platform gives the migrations each app published, which aicoded dev applies to the app's
// database before its draft. It is asked at the app's first start, and at an explicit start or
// restart once its last answer is a minute old; otherwise, and with nil, they come from the
// app's cache.
Platform migrations.Platform
}
Config is what Open runs a workspace with.
type Gateway ¶
type Gateway struct {
// contains filtered or unexported fields
}
Gateway fronts apps at http://<app>.localhost:<port>, and serves the dev UI at http://localhost:<port>. It stands in for the company login: every request reaches the app with a fresh viewer token for the persona chosen on /_aicoded/persona, and any token the client sent is replaced. An app that is starting, failed or stopped gets a page that says so instead.
func NewGateway ¶
NewGateway returns a gateway for apps served on port, which serves ui at the bare host. With no personas, a viewer is the one persona no-roles.
func (*Gateway) Add ¶
Add routes <name>.localhost to the app listening on socketPath. When the app does not answer, the host answers 502 with a page, and st keeps and prints a runner ERROR entry that says why. The proxy's other errors, such as an answer cut off on the way, st keeps as runner WARN entries without printing them.
func (*Gateway) AddManual ¶
AddManual routes <name>.localhost to the app the developer runs by hand, on socketPath. While the app does not answer, the host answers 503 with a page that shows command.
type Instance ¶
type Instance struct {
Name string
// Manifest is the app's permission list, with the sections aicoded generate wrote.
Manifest manifest.Manifest
// contains filtered or unexported fields
}
Instance is one app running under the local runner.
func Start ¶
func Start(ctx context.Context, dir string, m manifest.Manifest, values devconfig.AppValues, svc Services, signer *Signer, out io.Writer) (*Instance, error)
Start builds the app in dir into the bin folder of svc.StateDir and runs it as launch does, with a store of its own that prints to out. It refuses an svc.StateDir that is not an absolute path.
type MySQLAdmin ¶
type MySQLAdmin struct {
// contains filtered or unexported fields
}
MySQLAdmin prepares app databases on the developer's MySQL server.
func NewMySQLAdmin ¶
func NewMySQLAdmin(dsn string) (*MySQLAdmin, error)
NewMySQLAdmin checks the admin DSN from dev.yaml. The server must be on this machine: a Unix socket, or TCP to 127.0.0.1 or ::1. Errors never quote the DSN, which holds a password.
func (*MySQLAdmin) Drop ¶
func (a *MySQLAdmin) Drop(ctx context.Context, app, env string) error
Drop drops the database and the users of app in env. It gives up after 30 seconds.
func (*MySQLAdmin) Migrate ¶
func (a *MySQLAdmin) Migrate(ctx context.Context, app, env string, steps []migrate.Step) (Users, error)
Migrate prepares the database and the users of app in env as Prepare does, and applies steps there as the owner with migrate.Apply, destructive steps too. When the database's journal does not start steps, or holds more steps than steps, Migrate first drops the database and makes it again, since it holds test data; it drops no other database. Every refusal of Apply, such as a list over its limits, is returned as it is. It returns the users.
func (*MySQLAdmin) Prepare ¶
Prepare creates the database and the two users of app in env when they are missing, gives each user a new random password, takes away every privilege it has and grants the data user SELECT, INSERT, UPDATE and DELETE and the owner everything on the app's own database only, and returns where each logs in. It gives up after 30 seconds.
type Options ¶
type Options struct {
// Manual names the apps the developer runs by hand, as aicoded dev --manual does.
Manual []string
// Login prints the login link of the dev UI, as aicoded dev does. Without it, as in aicoded
// mcp, the line names only the dev UI's address.
Login bool
}
Options are what the developer chose for Host and Run.
type Ring ¶
type Ring[T any] struct { // contains filtered or unexported fields }
Ring keeps the last n values added.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner serves the runner protocol to one app that another program starts, through the runner server with the providers of aicoded dev. Its mail is caught and never sent, as under aicoded dev, it calls no other app, it refuses every request to an outside service, and it logs nothing.
func NewRunner ¶
NewRunner starts serving the runner protocol to the app of m as opts say. A fresh form key signs the app's form tokens.
func (*Runner) Close ¶
func (r *Runner) Close()
Close stops serving, which removes runner.sock and mysql.sock.
type RunnerOptions ¶
type RunnerOptions struct {
// Dir is the folder where the runner makes runner.sock, and mysql.sock for an app that
// declares sqldb. The app makes app.sock there.
Dir string
// FilesDir holds a folder for each file store the app declares, made when missing.
FilesDir string
// Values hold a value for each setting and secret the app declares.
Values devconfig.AppValues
// Env is the environment the app runs in: devconfig.EnvDev or devconfig.EnvPreview.
Env devconfig.Env
// Version is the version of the release that Hello reports.
Version string
// ViewerKey verifies the viewer tokens the app accepts.
ViewerKey ed25519.PublicKey
// do the same with app.sock: for an app that runs as another user. Dir then decides who
// reaches them.
Share bool
// MaxSpans and MaxSpanBytes bound the spans the runner keeps: the first MaxSpans spans of at
// most MaxSpanBytes of text in all. Both must be positive.
MaxSpans, MaxSpanBytes int
// Database is where the proxy on mysql.sock logs in. It is set exactly when the app declares
// sqldb.
Database *mysqlproxy.Upstream
// OnDatabaseError, if set, gets each reason the proxy could not open the app's database.
// It may be called from several goroutines at once.
OnDatabaseError func(error)
}
RunnerOptions configure NewRunner.
type Services ¶
type Services struct {
// StateDir is the workspace's private folder from StateDir, an absolute path; file stores
// and built apps live under it.
StateDir string
// MySQL creates the apps' databases; nil when dev.yaml names no MySQL server.
MySQL *MySQLAdmin
// Router carries the app's calls to the other apps of the workspace; with nil, every call
// fails with E-RPC-011.
Router *server.Router
// Env is the environment the app runs in, which also names its database: devconfig.EnvDev
// when empty, or devconfig.EnvPreview.
Env devconfig.Env
// Platform gives the migrations each app published; with nil, they come from the app's
// cache, .aicoded/migrations.json.
Platform migrations.Platform
// contains filtered or unexported fields
}
Services are what the local runner gives an app besides the runner protocol.
type Signer ¶
type Signer struct {
// contains filtered or unexported fields
}
Signer mints viewer tokens for personas; it stands in for the company login.
type Users ¶
type Users struct {
// Data may only read and write rows: it has SELECT, INSERT, UPDATE and DELETE on the app's
// database and nothing else. The proxy logs in with it.
Data mysqlproxy.Upstream
// Owner has every privilege on the app's database and nothing else. Only the migrations run
// as it; the app never gets it.
Owner mysqlproxy.Upstream
}
Users are the two accounts of an app's database.
type Workspace ¶
type Workspace struct {
// contains filtered or unexported fields
}
Workspace runs the apps under a folder on the local runner. Each app has a slot that generates, builds and starts it; an app that fails stops only itself, and its host shows its problems until it starts again.
func Host ¶
Host starts aicoded dev for dir with the settings in dev.yaml, watching, and serves its control socket. Close on the workspace also closes the socket. It refuses a dir with no app before it reads dev.yaml, and, with E-DEV-012, a dir that an aicoded dev runs for already, directly or through a folder above it, or that holds a folder an aicoded dev runs for. It claims the control socket before it starts any app, so that two starts never both build. dev.yaml is read again at every start of an app, for its values.
func Open ¶
Open serves the dev UI, then starts the apps under cfg.Root, each after the apps it calls, and returns once each is running, runs by hand or has failed. The dev UI's access token is kept in cfg.State, which must exist. Only a problem of the whole workspace makes it fail: no app, two apps with one name, a name in cfg.Manual that no app has, a token file that is not valid, the gateway port in use or a MySQL server dev.yaml cannot name.
func (*Workspace) Changed ¶
func (w *Workspace) Changed() <-chan struct{}
Changed returns a channel that is closed at the next change of the workspace: the state of an app, or a log entry, a span or a message that an app sent or received.
func (*Workspace) Close ¶
func (w *Workspace) Close()
Close stops the control socket, then watching, then the gateway and then the apps, the last started first.
func (*Workspace) MailReceive ¶
func (w *Workspace) MailReceive(_ context.Context, app string, m devapi.InboundMail) (string, error)
MailReceive puts m into the inbox of app, running or not, and returns its id.
func (*Workspace) Personas ¶
Personas returns the personas a viewer of the apps can be: those of dev.yaml, or else the default ones, which follow the roles of the apps.
func (*Workspace) Rescan ¶
Rescan starts the apps that appeared under the workspace root since it last looked, and stops those that are gone, whose aicoded.yaml is gone or whose name changed. A new app with the name of another fails with E-DEV-010 and leaves the other running. A new folder whose aicoded.yaml does not load starts nothing; Rescan prints its error once, and again when it changes.
func (*Workspace) Restart ¶
Restart generates, builds and starts the app named app again, also when the developer stopped it, and returns its state after. For an app run by hand, it generates the app and keeps its runner, unless the runner is down or the permission list or the dev.yaml values changed; then it brings up a new runner. It runs on the workspace's context, not on ctx, so only Close ends it early.
func (*Workspace) SetManual ¶
SetManual switches the app named app into manual mode, where the developer runs it by hand, or back. It returns at once and switches in the background; a stopped app stays stopped.
func (*Workspace) Start ¶
Start starts the app named app, or restarts it when it runs; for an app run by hand, it brings up a new runner. It returns at once and starts the app in the background.
func (*Workspace) Stop ¶
Stop stops the app named app until Start or Restart. The app is not rebuilt when its files change. Stop returns at once and stops the app in the background.
func (*Workspace) Traces ¶
func (w *Workspace) Traces(_ context.Context, q devapi.TraceQuery) ([]devapi.TraceSummary, error)
Traces returns the newest traces of the app q names, or of every app, newest first.