S1 Connecting the app and the research

How the Strom app connects with the research on the same computer, what kinds of trees come of it and what happens when the connection fails. Describes the Strom app 3.21.2 (and the research 1.25.2). Changes from a later version carry its number. What happens to edits after connecting is described in S2, the phone in S5.

S1.1 The research's bridge runs only on this computer

The app talks with the research through a bridge: a small server the research starts on this computer. The bridge listens only at the address 127.0.0.1, on a random port, and each of its addresses carries a secret key. The tree's data go nowhere else through the bridge.

• Limits:
  • The bridge accepts a request only from a page of the Strom app on stromapp.info or from a local address. When its key comes from a foreign page, the research replaces the key at once and that request gets no answer.
  • The bridge runs until the user switches it off (strom live stop, in the app the switch Research on, S1.9), or until the computer shuts down. It stops by itself only when the user chose so (live.idleMinutes, in the app After 2 hours without work): when nobody asks it anything for that time and nobody works in the tree meanwhile. The app's regular status request does not keep the bridge alive.
  • The bridge also stops by itself when its research disappears from the folder and is still missing at the next check at least 10 s later. A disk unavailable only for a moment does not stop the bridge. A second bridge of the same research started next to a running one stops at once.
  • When the bridge restarts by itself (update, inactivity, crash), it keeps its address: the same port if it is free, and the same key. The app then connects without a new link.
  • strom live stop throws the key away: only strom app then connects the app again. When the port is taken by another program, the bridge takes another port and the app needs a new link.
  • The bridge refuses a write when the tree is sealed on another computer, when the tree's files in a cloud folder are not downloaded yet, and when the disk is full. Edits then wait in the app (S2).
• Controls: terminal: strom live (is the bridge running?), strom live start, strom live stop (--forget forgets the port too), strom config set live.idleMinutes <minutes> (0: never by itself, the default). The run log is in the research folder in .strom/live.log.
• Since: research 1.0.0. The same address after a restart from 1.8.0, live.idleMinutes from 1.25.0.
• From research 1.29.0: the bridge no longer stops by itself when idle (the default live.idleMinutes is 0); before, it stopped by itself after two hours. A value the user saved stays.
• From research 1.30.0: a bridge whose research disappeared stops only after a second check at least 10 s later (before, at once); a second bridge of the same research stops at once.
• From research 1.31.0: one bridge per research stays even after an update. A bridge running beside the research's bridge (the one .strom/live.json names) stops by itself at the next check (every 10 s). A bridge whose strom an update deleted stops too and says so in .strom/live.log. A new bridge that stops because another bridge holds the research also stops the bridge that started it for the hand-over, unless that is the research's bridge. Handing the bridge over to a newer strom is quicker: the old bridge answers while the new strom is checked.

S1.2 The research opens in the app through a link from the terminal

The research is opened in the app by the command strom app. The research starts the bridge and opens the app in the browser with a link to its tree. The first time a new tree is created in the app, the next time the same one is updated.

• Limits:
  • When an agent works in the tree (or with the option --live), the app follows the tree live right away (S1.4). Otherwise it loads the tree once.
  • The app takes only a link to 127.0.0.1 or localhost. It ignores any other link with the message "The link pointed to a file that is not on this computer, so it was ignored."
  • The tree from the research is already in the app and has not changed in the app since the last load: it is updated. It has changed: the app asks whether to Update it or Open as copy. A backup is saved before the update.
  • Safari does not let a web page connect to a program on this computer. strom app therefore never opens Safari. Without a suitable browser the installed app takes the file over, or the file output/tree-strom.ged from the research folder can be dragged into the app window.
  • Chrome and Edge ask the first time for permission to access devices on the local network. Without it the app cannot reach the research (S1.5).
• Controls: terminal: strom app, strom app --live. App: Research → Other actions → Research for this tree…
• Since: app 3.0.0, research 1.0.0
• Since research 1.30.0: on macOS the research hands the address for the app installed from a Chromium browser (Chrome, Edge…) to the browser already running, as its own second start would hand it over. No other program starts and no browser icon is added to the Dock. When the browser is not running or does not answer within 5 s, the research starts it as before.

S1.2.1 Links the app accepts

The app removes the parameters from the address after processing them. When the page is reloaded during following, following resumes silently.

S1.3 Kinds of trees in the app

A tree in the app is either its own, or it belongs to a research on this computer. A tree from the research carries in its file the number of the research and the version it came from. By that the app knows where to send it back.

• Limits: whether a tree is a research or an archive is decided by the research, not by the app. It can be switched only in the research.
• Controls: app: the tree switcher. Terminal: the research menu.
• Since: app 3.12.0 (the name Strom archive), marks in the switcher from 3.16.0

S1.4 Following live

When following live, changes from the research come into the app by themselves. The followed tree is read-only meanwhile, so that an edit in the app does not meet the agent's work.

• Limits:
  • Only one tree is followed live at a time. Following another tree ends the previous one.
  • Switching to a tree where an agent works starts following it without asking. Unsent edits of the open tree are sent first.
  • Following ends when the agent stops working or when the research becomes an archive. The tree can then be edited again.
  • When automatic following fails, the app stays silent and the tree stays as it was.
• Controls: app: Follow live · terminal: strom app --live
• Since: app 3.0.0; switching to a tree with an agent from 3.13.1
• From app 3.26.0 with research 1.30.0:
  • the research has the tree for the app built for each state and keeps it even after the bridge starts again;
  • the app shows the tree at once in its last built form. When the research has moved on meanwhile, the research panel shows “Preparing a newer version…” and the newer version replaces the tree by itself once it is ready;
  • when the research has not changed since the last load and the tree in the app is still exactly the one loaded, the app neither downloads nor loads it again;
  • while following, the research announces a change once its tree is ready.

S1.5 When the research is not running or the connection fails

When the app does not reach the research, the tree in the app does not change and edits in it wait. What exactly happened, the app shows in the window Couldn't connect to the research.

• Limits:
  • The window always says that nothing has changed and the tree stays as it was. Try again tries the connection again.
  • A tree from the research can be edited even when the research is not running. Edits are sent when the research connects again.
  • The bridge runs but does not answer: strom live stop and a new start help.
• Controls: app: Try again, Close, How to allow · terminal: strom app --live, strom live stop
• Since: app 3.9.0

S1.6 Older and newer versions

The app and the research are released separately. The research tells the app in its status what it can do, and the app turns on only what the research accepts. The research in turn chooses by the app's version what it sends.

• Limits:
  • Older research (without automatic sending, or without titles): the app shows The research has an older version (v) with the offer Update the research. Edits are then sent only by hand: the app starts the research in the terminal and the research takes them. Until the update, titles stay only in the app.
  • A new version of the research is available: the app shows New Strom Research … with the button Update. What is running finishes on the current version.
  • A research written by a newer version of the strom program: an older program neither opens it nor writes into it.
  • A tree saved by a newer version of the app: it is read-only in the app until the app is updated.
• Controls: app: Update the research, Check again · terminal: strom update
• Since: app 3.9.0 (research 1.12.0); read-only tree from app 3.19.0
• From app 3.22.0: directions from the app and the panel without a connection are turned on only with research 1.26.0 (S4).

S1.7 Several researches on one computer

Each tree from a research has its own bridge. The app also asks the bridges of trees that are not open right now and shows their state in the tree switcher.

• Limits:
  • Marks at a tree in the switcher: live (followed), running or N directions (an agent works), N waiting (items to deal with), not running.
  • It always asks only one bridge at a time and only when the page is visible: the first time after 3 seconds, then every minute. It waits at most 1.5 seconds for an answer.
  • A research that is not running connects again when its tree is opened from the research (strom app).
• Controls: app: the tree switcher; the research panel, row Elsewhere
• Since: app 3.13.1

S1.8 Data stay on the computer

The app keeps trees in the browser's storage on this device. The research keeps its tree in its folder on the disk. Between them the tree travels only through the bridge on this computer (S1.1).

• Limits:
  • Each browser has its own storage. A tree opened in Chrome is not in Edge.
  • The tree in the app and the tree in the research are two copies. The main one is the tree in the app, the research has its own copy, and what the research does not write is always visible in the app (S2).
• Since: app 3.0.0

S1.9 Research on: the bridge's switch at a tree

Each tree from a research on this computer has the switch Research on in the app. It shows the bridge's real state: on when the bridge answers, otherwise off. A bridge switched on runs until it is switched off with the switch or strom live stop, until the computer shuts down, or as the setting Switch research off when idle says.

• Limits:
  • Switching off stops the bridge like strom live stop, except that the bridge keeps its address (port and key). A bridge switched off stays off: new work in the tree does not bring it back. The tree in the app stays and can still be edited (S1.5). Under the switch: "Switched off. It stays off until switched on again."
  • A bridge switched off by idleness comes back by itself with new work in the tree, at the same address. Under the switch: "Switched off after a time without work. New work in the tree switches it on again."
  • Switching on sends the research a link that starts only the bridge at its last address, without a window. When nothing happens, or the research cannot be switched on from the app, the app shows the command strom live start (to run in the terminal, in the tree's folder) with the button Copy. An older research that cannot be switched off from the app likewise shows the command strom live stop.
  • After the computer shuts down or restarts, the bridge is not running and does not start by itself. The user switches it on: Switch on in the research panel, or strom live start.
  • Switch research off when idle has two choices: Until the computer shuts down (the default) and After 2 hours without work. It holds for all trees on this computer and the research keeps it (live.idleMinutes 0 or 120). Running bridges take it within a minute. A value set in the terminal shows as Own value (N min). When no research that takes the choice is running, the app shows the commands for the terminal instead of the choices.
  • Phones and tablets have no switch (the research runs on a computer). A copy of a tree from a research has no switch.
• Controls: app: the switch Research on in the research panel (a tree not followed live, and after following ended) and in Manage trees at the tree's row; the research panel when the research is not running: Switch on; Settings → Research on this computer → Switch research off when idle. Terminal: strom live start, strom live stop, strom config set live.idleMinutes 0 (until the computer shuts down) or 120 (after 2 hours without work).
• Since: app 3.25.0, research 1.29.0