dev

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 62 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultPersonas

func DefaultPersonas(ms ...manifest.Manifest) []devconfig.Persona

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

func FindRunning(ctx context.Context, dir string) (root, socket string, ok bool)

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

func Run(ctx context.Context, dir string, out io.Writer, opts Options) error

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

func RunningLogin(ctx context.Context, dir string) (string, bool)

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

func Skip(rel string) bool

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.

func StateDir

func StateDir(root string) (string, error)

StateDir returns the folder of StatePath. It creates the folder with mode 0700 and refuses one that other users can read.

func StatePath

func StatePath(root string) (string, error)

StatePath returns the private folder of the workspace rooted at root, a folder named by a hash of root under ~/.local/state/aicoded, without creating it.

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

func NewGateway(port int, personas []devconfig.Persona, signer *Signer, ui http.Handler) *Gateway

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

func (g *Gateway) Add(name, socketPath string, st *store)

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

func (g *Gateway) AddManual(name, socketPath, command string)

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.

func (*Gateway) Fail

func (g *Gateway) Fail(name string, ps []problem.Problem)

Fail answers <name>.localhost with a 503 page that lists ps.

func (*Gateway) Personas

func (g *Gateway) Personas() []devconfig.Persona

Personas returns the personas a viewer can choose from.

func (*Gateway) Remove

func (g *Gateway) Remove(name string)

Remove answers <name>.localhost with 404, as for a name no app has.

func (*Gateway) ServeHTTP

func (g *Gateway) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Gateway) Starting

func (g *Gateway) Starting(name string)

Starting answers <name>.localhost with a 503 page that reloads itself every second.

func (*Gateway) Stopped

func (g *Gateway) Stopped(name string)

Stopped answers <name>.localhost with a 503 page that says the app is stopped and where to start it.

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.

func (*Instance) AppSocket

func (i *Instance) AppSocket() string

AppSocket returns the path of the app's HTTP socket.

func (*Instance) Exited

func (i *Instance) Exited() <-chan struct{}

Exited is closed when the app process ends, or, for an app run by hand, when Stop stops its runner.

func (*Instance) Stop

func (i *Instance) Stop()

Stop sends SIGTERM, waits for the app to exit (killing it after 15s) and removes its sockets. For an app run by hand, it stops only the runner, keeps the run folder and closes Exited.

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

func (a *MySQLAdmin) Prepare(ctx context.Context, app, env string) (Users, error)

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.

func NewRing

func NewRing[T any](n int) *Ring[T]

NewRing returns a ring that keeps n values.

func (*Ring[T]) Add

func (r *Ring[T]) Add(v T)

Add keeps v, dropping the oldest value when the ring is full.

func (*Ring[T]) All

func (r *Ring[T]) All() []T

All returns the kept values, oldest first.

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

func NewRunner(ctx context.Context, m manifest.Manifest, opts RunnerOptions) (*Runner, error)

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.

func (*Runner) Ready

func (r *Runner) Ready() <-chan struct{}

Ready is closed once the app reports that it accepts requests.

func (*Runner) Spans

func (r *Runner) Spans() ([]devapi.Span, uint64)

Spans returns the spans the runner kept, oldest first, and how many it did not keep: past its bounds, or dropped by the app or the runner server before they reached it.

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
	// Share makes runner.sock and mysql.sock usable by every user, and has Hello tell the app to
	// 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.

func NewSigner

func NewSigner() (*Signer, error)

NewSigner returns a signer with a fresh key.

func (*Signer) Mint

func (s *Signer) Mint(p devconfig.Persona, app string, now time.Time) (string, error)

Mint returns a viewer token that lets persona p use app.

func (*Signer) MintCall

func (s *Signer) MintCall(v *viewer.Claims, caller, callee string, now time.Time) (string, error)

MintCall returns the token of a call from the app caller to the app callee: on behalf of the viewer v, or of the calling app itself when v is nil.

func (*Signer) Public

func (s *Signer) Public() ed25519.PublicKey

Public returns the key apps verify tokens with.

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

func Host(ctx context.Context, dir string, out io.Writer, opts Options) (*Workspace, error)

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

func Open(ctx context.Context, cfg Config) (*Workspace, error)

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) Logs

Logs returns the newest log entries that match q, oldest first.

func (*Workspace) Mail

func (w *Workspace) Mail(_ context.Context, app string) ([]devapi.MailSummary, error)

Mail returns the mail app sent, then its mailbox, each newest first.

func (*Workspace) MailGet

func (w *Workspace) MailGet(_ context.Context, app, id string) (devapi.Mail, error)

MailGet returns the message id that app sent or has in its mailbox.

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

func (w *Workspace) Personas() []devconfig.Persona

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

func (w *Workspace) Rescan(ctx context.Context)

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

func (w *Workspace) Restart(_ context.Context, app string) (devapi.App, error)

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

func (w *Workspace) SetManual(app string, on bool) error

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

func (w *Workspace) Start(app string) error

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) Status

func (w *Workspace) Status(context.Context) (devapi.Status, error)

Status returns the state of every app, in folder order.

func (*Workspace) Stop

func (w *Workspace) Stop(app string) error

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) Trace

func (w *Workspace) Trace(_ context.Context, id string) (devapi.Trace, error)

Trace returns every span of the trace id, from every app, by start.

func (*Workspace) Traces

Traces returns the newest traces of the app q names, or of every app, newest first.

func (*Workspace) WhatBroke

func (w *Workspace) WhatBroke(_ context.Context, app string) (devapi.Broken, error)

WhatBroke returns the problems of the failed apps and their latest errors and failed spans, of app or of every app.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL