notesy::net

Requests to the web, and only to the sites the plugin names in [net] (plugin.toml). Naming hosts there asks for the net permission; the module is there only once the user grants it. A script has no other way to the network.

rustuse notesy::{json, log, net};

pub fn ready() {
    net::fetch("https://api.example.com/v1/today", |result| {
        let response = result?;
        if response.ok {
            let today = json::parse(response.text)?;
            log::info(`${today.count} things today`);
        }
    });
}

#net::fetch(request, then)

Sends request on notesy's own threads and returns straight away. When the answer is in, notesy calls then(result) on the script's thread: Ok(response), or Err(why) when it couldn't be made (the site can't be reached, it took too long, an address it was sent on to isn't one the plugin names). An answer the site gives, 404 or 500 included, is Ok; check response.ok or response.status.

request is an address, for a GET, or an object:

Field What it is
url The address: https://, on a host in [net]. Plain http:// only to this computer or the local network.
method GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS. POST when there's a body, otherwise GET.
headers An object of header names and text. Host, Content-Length, Connection and the like are notesy's to set.
body Text to send.
json A value to send as JSON, with Content-Type: application/json.
form An object to send as a form, with Content-Type: application/x-www-form-urlencoded.
account One of its [[accounts]]: notesy adds its token as Authorization, to one of that account's own sites only (notesy::accounts).

At most one of body, json and form. An address or a field that's wrong is an error where fetch is called, not in then.

The response:

Field What it is
status The status code, like 200.
ok Whether it's 200 to 299.
url Where it came from in the end, after any redirects.
headers An object of the headers, by lowercase name.
text The body, as text.

#net::encode(text)

text percent-encoded for an address: every byte but letters, digits, -, ., _ and ~, so it can go in a query.

rustuse notesy::{log, net};

pub fn ready() {
    let url = `https://geocoding-api.open-meteo.com/v1/search?name=${net::encode("São Paulo")}`;
    log::info(url); // …?name=S%C3%A3o%20Paulo
}

#What notesy checks

  • Every address, the first and every one a redirect sends it on to, is checked against the plugin's hosts before it's reached. An account's token goes only to that account's own sites, and not on to another a redirect sends it to.
  • A site's name that leads to this computer or the local network is refused, unless the plugin names that address itself: a site can't point its name at the user's router.
  • Addresses are read strictly: no credentials before the host, no percent-encoded or non-ASCII host names, no hosts written as numbers.
  • A request takes at most 30 seconds, sends at most 10 MB and takes back at most 10 MB. A script has at most 16 requests going at once.
  • Redirects are followed up to five times.
  • No proxy is used, so what's checked is what's reached.

A script's handlers run one at a time, so then never runs while another of its calls is still going.

#What it reached

A plugin's page in Settings lists the sites in its [net] and, for each, how many requests it made there this session and when the last was, or that it hasn't reached it yet. It's kept in memory only; nothing about it is written anywhere.

Every page