aicoded.dev

Calls between apps

An app can call Go functions of another app as if they were its own. The called app declares who may call each function; aicoded generate writes the code on both sides; and the runner carries each call, checks it against the permission lists of both apps, and passes the viewer on.

Serving calls

The called app puts its functions in its rpc/ folder, package rpc. Each exported function has the shape func Name(ctx context.Context, in In) (Out, error), where In and Out are exported structs declared in rpc/, and an //ssr:access line in its doc comment. The contacts example serves one:

// Contacts returns the contacts of a person to that person and to hr. The people app checks the
// same rule in its Guard; this app checks it again, since it holds the data.
//
//ssr:access caller=people role=staff
func Contacts(ctx context.Context, in ContactsIn) (ContactsOut, error) {
	if !allowed(auth.Viewer(ctx), in.Login) {
		return ContactsOut{}, frameworkrpc.Error(frameworkrpc.PermissionDenied, "only the person and hr may read these contacts")
	}
	phones, emails, err := deps.Contacts(ctx, in.Login)
	if errors.Is(err, deps.ErrNoPerson) {
		return ContactsOut{}, frameworkrpc.Error(frameworkrpc.NotFound, "no such person")
	}
	if err != nil {
		return ContactsOut{}, err
	}
	return ContactsOut{Phones: phones, Emails: emails}, nil
}

The framework's rpc package is imported under another name, frameworkrpc, because the folder's own package is rpc too.

The rule in //ssr:access is checked before the function runs. Ownership is the function's own check: Contacts refuses a viewer who is neither the person nor hr, even though the calling page checked the same rule, because the app that holds the data never trusts its caller to have checked.

The types

The fields of In, Out and the structs they use are exported and named, not embedded. Each field has one of these types:

int, uint, the 8- and 16-bit integers, maps, arrays, interfaces, types of other packages, slices of pointers and pointers to slices are refused; use int64 for whole numbers.

The generated files

aicoded generate writes two files; never edit either:

A field keeps its number, and the number of a removed field is never used again in its struct. A struct that no function reaches any more, or that is renamed, loses its numbers: when it comes back, or under its new name, its fields are numbered afresh. Removing or renaming a function or a field, or changing a field's type or number, breaks the apps that call it. Before it writes anything, aicoded generate checks the change against every snapshot of the app that another app of the workspace holds, and refuses one that breaks a snapshot (E-RPC-013); in aicoded dev, the called app then fails alone. Add a new field or function instead. A refused change leaves .aicoded/rpc.json as it was, so undoing the change in rpc/ is enough; to keep it, run aicoded rpc add <app> in each calling app and update its calls. A snapshot edited by hand is refused (E-RPC-005).

main passes the generated server to app.Main as RPC, next to Handler when the app has pages. An app with no pages passes only RPC:

// Contacts serves the phone numbers and email addresses of people to the people app.
package main

import (
	"aicoded.dev/framework/app"

	"contacts/deps"
	"contacts/rpc"
)

func main() {
	app.Main(app.Options{RPC: rpc.Server(), OnStart: deps.Start})
}

Calling

In the calling app's folder, run aicoded rpc add contacts. It looks for the app named contacts in the folder that holds the calling app's folder and below it, generates it, and copies its snapshot to .aicoded/services/contacts.json. Then it generates the calling app, which writes the client services/contacts/client_gen.go, package contacts: the app's name without dashes, so billing-eu gets services/billingeu/. Run it again to pick up the called app's new functions. The folder of a client holds only the generated client (E-RPC-014).

Before it writes anything in the calling app, aicoded rpc add refuses:

The client has a function of the same name and types for every function of the called app. Call it with the context of the request being served, and turn the codes you expect into answers:

// Data asks the contacts app for the user's phones and emails, on behalf of the viewer.
func (p *DP) Data(ctx context.Context, r *web.Request, _ web.ResponseWriter, data *RouteData) error {
	out, err := contacts.Contacts(ctx, contacts.ContactsIn{Login: r.URLParam("login")})
	switch rpc.CodeOf(err) {
	case 0:
	case rpc.PermissionDenied:
		return web.Forbidden()
	case rpc.NotFound:
		return web.NotFound()
	default:
		return err
	}
	data.Phones, data.Emails = out.Phones, out.Emails
	return nil
}

Viewers and apps

Errors

Deadlines

A call follows the deadline of its context, or gets 10 seconds when the context has none. The runner cuts every call at 30 seconds. A call cut short fails with an error that errors.Is matches with context.DeadlineExceeded, or context.Canceled when its context was cancelled.

The services section

aicoded generate writes the services section of the permission list, as it writes access. Never edit it. In the examples it is:

# people/aicoded.yaml
services:
  calls:
    "contacts": ["Contacts"]
# contacts/aicoded.yaml
access: {}
services:
  serves:
    "Contacts":
      callers: ["people"]
      require: ["staff"]

Several apps in aicoded dev

Run aicoded dev in a folder above the apps, such as examples/, which holds people/ and contacts/. It finds and generates every app, checks the snapshots each app holds, and starts each app after the apps it calls, so an app may call them in OnStart. It prints aicoded dev: contacts (calls only) for an app that has no pages and serves calls. See aicoded dev.

See also

Markdown · Source on GitHub · framework f46741f