Reference

System

Edge Python reaches outside its sandbox through four system modules.

They ship inside Edge Python and need no imports entry. A package can import one only when the root edge.json grants it.

import fs
import net
import time
import secret

Permissions

The root edge.json grants each package it imports. Each package passes grants on to the ones it imports. A permissions section maps each holder to a list of entries, each written module:scope.

{
  "imports": { "analytics": "1.2.0" },
  "permissions": {
    "main": ["net:api.example.com", "time:wall", "time:zone"],
    "analytics": ["net:api.telemetry.com", "time:monotonic"]
  }
}

Each scope follows a few rules.

• A net host is a lowercase name or an IPv4 written as a.b.c.d. It carries no scheme and no port.
• IPv6 is not supported. The policy of a browser frame cannot name one.
• A secret name is uppercase letters, digits and underscores. It never starts with a digit.
• An fs folder is written from the root edge.json. fs:./shop reaches shop/Gemfile and never shopping/.
• An entry without a scope, such as "net", lets the package import the module and reach nothing.

Path prefixes

net:api.example.com/v2 reaches /v2 and /v2/items and no other path. A path counts as under the prefix only if it stays there however a server reads it.

• It may be decoded once or twice.
• A backslash may be taken for a slash.
• A ; parameter may be dropped.

Under that grant /v2/..%2fadmin and /v2/..;/admin are refused. /v2/group%2Fproject reaches.

Who holds what

A package is what an import key brings in, the nearest edge.json above its files.

• A package holds what its importer writes under its key, joined with what the importer writes for all.
• An importer other than the root passes on only what it holds itself.
• The name a manifest gives itself never counts. No package can pose as another.
• Code reached by a relative import belongs to the package that imports it, even under an edge.json of its own.
• A package two importers share loads once for each. Each copy holds only what its own importer passes it.
• Code outside any package holds nothing.

What a dependency asks for and passes on

A dependency writes in its own edge.json what its code needs under main. It writes what each package it imports needs under that import key. It passes on only what it holds, and its importer has to give it everything it lists.

A generic client such as http asks for "net" alone. The package that imports it passes the hosts.

{ "name": "analytics", "imports": { "http": "0.2.0" }, "permissions": { "main": ["time:monotonic"], "http": ["net:api.telemetry.com"] } }

The CLI holds the tree to these asks at every step.

• edge add prints what each new package asks for.
• edge lock walks the whole tree, each package through its own edge.lock. It writes nothing until the root gives each package it imports everything that package lists, and it names each one that misses something.
• A package that passes an import less than it asks fails the lock the same way.
• edge build, edge run and edge test run the same check before anything compiles. An edit after the last lock cannot slip past it.

error: edge.json does not grant what these packages ask for
  analytics 1.2.0   net:api.telemetry.com, time:monotonic
help: grant them under "permissions" in edge.json

No import may be named all, main or eval. The package it brings in would answer to that holder. The registry refuses to publish a package named any of them.

Where a grant is checked

Importing a system module the package holds no entry for fails at compile time.

'analytics' imports net, which edge.json does not grant it

Every call checks its scope again, since a url is only known once the program runs. A call outside the grant raises PermissionError in the coroutine that made it. PermissionError is a subclass of OSError.

import net

try:
    net.request("GET", "https://evil.example/")
except PermissionError as e:
    print(e)  # 'main' has no net:evil.example, edge.json grants it net:api.example.com

A request or socket belongs to the package that opened it. Another package cannot read it. A malformed section stops the run before anything compiles, naming the holder and the entry.

time

Without any time scope a run uses a virtual clock. sleep and with_timeout pass at once and in order, and a host call takes no time. What a program prints then never depends on when it runs.

Any time scope turns the wall clock on for the whole run.

net

headers is a list of [name, value] pairs or a dict. body is bytes, a str or None. A failure to connect or read raises OSError from the call that meets it.

import net

r = net.request("GET", "https://api.example.com/items", [["accept", "application/json"]], None)
status, headers = net.response(r)
body = b""
chunk = net.read(r)
while chunk is not None:
    body += chunk
    chunk = net.read(r)

URL rules

The check and the request always read the same host and exactly one path. The path is resolved before the check and sent as resolved.

In a browser the request is a fetch from the Web Worker, and CORS applies on top of the grant. The CLI runs the same calls in SpiderMonkey, with its own HTTP and WebSocket clients underneath. A program answers the same with and without --web.

secret

A name the package does not hold raises PermissionError. A name it holds but the host keeps no value for raises OSError.

Nothing lists the names a host keeps. A program reads only the values it was granted and asks for by name.

• The CLI reads EDGE_SECRET_<name> from its environment at the moment of the call. A program never reaches a variable it was not granted, whatever else the environment holds.
• With --web the CLI hands the page only the values a secret entry names.
• A page that embeds the engine passes them to createWorker as secrets.

import secret

token = secret.read("GITHUB_TOKEN")

EDGE_SECRET_GITHUB_TOKEN=ghp_example edge run main.py

fs

A path is written from the root edge.json, such as shop/app/product.rb. Nothing writes.

Each host reads the files its own way. Both read the same files.

• The CLI reads the disk, or the bundle a run came in. It never follows a link, even one pointing inside the project.
• A page reads the files beside its program through the same reader its imports use.
• HTTP cannot list a folder. A page lists files from edge.files, the list edge build --web writes and edge serve and --web answer.
• A page reads only the paths that list names.
• A page that embeds the engine serves edge.files beside its edge.json, a JSON list of every path fs may read.

{ "permissions": { "main": ["fs:./shop"] } }

import fs

for path in fs.list("shop"):
    print(path)

code = fs.read("shop/app/models/product.rb")

batch

Every system module also takes batch(calls). calls is a list of [name, *args] lists answered in one crossing, and the results come back in the same order.

• A call that waits holds the batch until every one settles.
• The first failure raises in the coroutine that made the batch.
• Each call still checks its own scope.

import net
import time

now, zone = time.batch([["now"], ["zone"]])
ids = net.batch([["request", "GET", url] for url in ["https://api.example.com/a", "https://api.example.com/b"]])
heads = net.batch([["response", i] for i in ids])

Each crossing between the program and the host pays to decode the arguments and encode the answer. A batch pays it once for all of its calls.

From a plugin

A .wasm plugin reaches these calls through the Sys op of the ABI.

In a page

A page passes grants, secrets and a trace switch to createWorker, described in JavaScript.

See also