Showing the changes to docs/architecture (1 of 12 files). Show all
Unified · Split
| @@ -32,17 +32,17 @@ the mismatch and action disappear. · 31 unmodified lines | |||
| 32 | 32 | ||
| 33 | The server resolves its capability once at startup and publishes it in the environment descriptor. | 33 | The server resolves its capability once at startup and publishes it in the environment descriptor. |
| 34 | 34 | ||
| 35 | | Advertised value | Process shape | Client behavior | | 35 | | Advertised value | Process shape | Client behavior | |
| 36 | | ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | 36 | | ----------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | |
| 37 | | `boot-service` | Linux server running under the T3-managed systemd user service | Call the update RPC; the service unit is replaced and restarted. | | 37 | | `boot-service` | Server running under the T3-managed systemd user service or macOS LaunchAgent | Call the update RPC; the managed service switches runtime and restarts. | |
| 38 | | `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | | 38 | | `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | |
| 39 | | `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | | 39 | | `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | |
| 40 | | absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | | 40 | | absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | |
| 41 | 41 | ||
| 42 | Desktop ownership takes precedence over process-shape detection. A desktop-managed backend must | 42 | Desktop ownership takes precedence over process-shape detection. A desktop-managed backend must |
| 43 | never spawn a second CLI server beside the app-owned process. Likewise, a process launched by an | 43 | never spawn a second CLI server beside the app-owned process. Likewise, a process launched by an |
| 44 | unrecognized systemd unit does not claim the foreground respawn path because its supervisor could | 44 | unrecognized systemd unit or marked LaunchAgent does not claim the foreground respawn path because |
| 45 | bring the old version back. | 45 | its supervisor could bring the old version back. |
| 46 | 46 | ||
| 47 | ## Update Flow | 47 | ## Update Flow |
| 48 | 48 | ||
| @@ -56,7 +56,7 @@ flowchart TD · 7 unmodified lines | |||
| 56 | F --> G[Run version preflight] | 56 | F --> G[Run version preflight] |
| 57 | G -->|fails| H[Remove failed runtime and keep current server] | 57 | G -->|fails| H[Remove failed runtime and keep current server] |
| 58 | G -->|passes| I{Handoff method} | 58 | G -->|passes| I{Handoff method} |
| 59 | I -->|boot-service| J[Rewrite and restart T3 systemd unit] | 59 | I -->|boot-service| J[Switch runtime and restart managed service] |
| 60 | I -->|respawn| K[Start delayed replacement and exit current process] | 60 | I -->|respawn| K[Start delayed replacement and exit current process] |
| 61 | J --> L[Client reconnects] | 61 | J --> L[Client reconnects] |
| 62 | K --> L | 62 | K --> L |
| @@ -77,10 +77,11 @@ preflight also removes the candidate runtime so retrying the same version perfor · 14 unmodified lines | |||
| 77 | 77 | ||
| 78 | ## Host Service Lifecycle | 78 | ## Host Service Lifecycle |
| 79 | 79 | ||
| 80 | The systemd user service is a host lifecycle concern, not a T3 Connect resource. The standalone | 80 | The systemd user service or macOS LaunchAgent is a host lifecycle concern, not a T3 Connect |
| 81 | `t3 service install`, `uninstall`, `update`, and `status` commands own it. Install and update both | 81 | resource. The standalone `t3 service install`, `uninstall`, `update`, and `status` commands own it. |
| 82 | reconcile the unit through `BootService`; running `npx t3@latest service update` therefore pins and | 82 | Install and update both reconcile the unit through `BootService`; running |
| 83 | activates the latest CLI release without requiring a connected client. | 83 | `npx t3@latest service update` therefore pins and activates the latest CLI release without requiring |
| 84 | a connected client. | ||
| 84 | 85 | ||
| 85 | The `t3 connect` onboarding flow may offer service installation, but it calls the same reconciliation | 86 | The `t3 connect` onboarding flow may offer service installation, but it calls the same reconciliation |
| 86 | operation as `t3 service install`. Connect logout only disables cloud access and clears its | 87 | operation as `t3 service install`. Connect logout only disables cloud access and clears its |
| @@ -88,9 +89,13 @@ authorization; it does not uninstall the host service. · 1 unmodified line | |||
| 88 | 89 | ||
| 89 | ## Process Handoff | 90 | ## Process Handoff |
| 90 | 91 | ||
| 91 | For `boot-service`, the server atomically rewrites the T3-managed user unit to point at the verified | 92 | For a systemd `boot-service`, the server atomically rewrites the T3-managed user unit to point at |
| 92 | runtime, reloads systemd, and restarts the unit. Reload and restart failures restore the previous | 93 | the verified runtime, reloads systemd, and restarts the unit. Reload and restart failures restore |
| 93 | unit before returning an error. | 94 | the previous unit before returning an error. |
| 95 | |||
| 96 | For a macOS `boot-service`, the LaunchAgent always starts a stable entry path. The server atomically | ||
| 97 | switches that path to the verified runtime and asks launchd to restart the job. A rejected restart | ||
| 98 | restores the previous runtime link before returning an error. | ||
| 94 | 99 | ||
| 95 | For `respawn`, the server starts a detached, delayed replacement that replays the original CLI | 100 | For `respawn`, the server starts a detached, delayed replacement that replays the original CLI |
| 96 | arguments. It then acknowledges the request and schedules the current process to exit. The delays | 101 | arguments. It then acknowledges the request and schedules the current process to exit. The delays |