Skip to content

Commit b4b6b2c

Browse files
docs(Air): refresh README with comprehensive developer documentation
Update the Air README with substantial new content covering: - Problem-first blockquote framing VS Code's cold-start and restart issues - Key Features section detailing native sidecar architecture, update management, authentication/signing, background downloader, and resource offloading - Deep Dive section with component breakdown linking to Source/, Update/, Download/, and Auth/ directories - System Architecture Diagram using Mermaid to illustrate Air's relationship with Mountain - Ecosystem table replacing the old terse section, documenting Daemon Process, Server Host, Update Delegate, Signer, and Traffic Manager roles - Getting Started guide with Cargo.toml installation, usage pattern (Spawn → Connect → Delegate → Monitor), and port allocation (50053 for Air, 50052 for Cocoon) - Expanded license section with CC0 explanation The new structure improves developer onboarding by leading with Air's value proposition and providing clear integration paths for working with the daemon.
1 parent b2abdca commit b4b6b2c

2 files changed

Lines changed: 105 additions & 34 deletions

File tree

Documentation/Rust

Submodule Rust updated 5285 files

README.md

Lines changed: 104 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@
4141

4242
# **Air** 🪁
4343

44+
The Native Background Daemon for Land 🏞️
45+
4446
> **VS Code cold-starts slowly because everything initializes fresh each launch.
4547
> Updates require a full restart that kills open terminals and in-progress work.
4648
> There is no mechanism to pre-stage work between sessions.**
@@ -52,31 +54,65 @@ update. No restart prompt ever."_
5254
[<img src="https://editor.land/Image/Rust.svg" width="14" alt="Rust" />](https://www.rust-lang.org/)&#x2001;[![Crates.io](https://img.shields.io/crates/v/Air.svg)](https://crates.io/crates/Air)
5355
[<img src="https://editor.land/Image/Rust.svg" width="14" alt="Rust" />](https://www.rust-lang.org/)&#x2001;[![Rust Version](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/)
5456

55-
Air is a persistent background daemon that keeps running after you close the
56-
editor. It pre-downloads and PGP-verifies the next version between sessions,
57-
pre-indexes workspace changes while the editor is closed, and keeps language
58-
server warm caches available. When you launch Land, the expensive work is
59-
already done. Cold start under 200 ms. Updates apply between sessions with no
60-
interruption.
61-
6257
📖 **[Rust API Documentation](https://Rust.Documentation.Editor.Land/Air/)**
6358

59+
Welcome to **Air**, the lightweight, persistent daemon that powers the
60+
background capabilities of the **Land Code Editor**. While `Mountain` handles
61+
the core application logic and UI, **Air** operates as a specialized sidecar
62+
process dedicated to heavy lifting, network operations, and system maintenance.
63+
It ensures that the main editor remains responsive by offloading
64+
resource-intensive tasks such as updates, large downloads, and cryptographic
65+
signing.
66+
67+
**Air** acts as the silent partner to `Mountain`, providing a robust server
68+
environment that persists even when the main editor window is closed, enabling
69+
seamless background updates and persistent state management.
70+
6471
---
6572

66-
## What It Does&#x2001;🔐
73+
## Key Features&#x2001;🔐
74+
75+
- **Native Sidecar Architecture:** Runs as a standalone process alongside the
76+
main `Mountain` application, communicating via high-performance IPC
77+
(gRPC/Vine) to handle requests without blocking the UI thread.
78+
- **Dedicated Update Management:** Takes full control of the update lifecycle,
79+
including downloading, verifying, and applying patches for `Land`, ensuring
80+
the editor is always up-to-date without user interruption.
81+
- **Isolated Authentication & Signing:** Manages sensitive cryptographic
82+
operations, including binary signing and secure login flows, keeping security
83+
logic isolated from the main application view.
84+
- **Background Downloader:** Implements a resilient download manager for
85+
extensions, language servers, and dependencies, capable of pausing, resuming,
86+
and handling network interruptions gracefully.
87+
- **Resource Offloading:** Acts as the designated handler for any "heavy" task
88+
that doesn't strictly require the main application loop, effectively
89+
decoupling infrastructure maintenance from the user experience.
90+
91+
---
92+
93+
## Deep Dive & Component Breakdown&#x2001;🔬
94+
95+
To understand how `Air`'s internal components interact to provide the background
96+
daemon functionality, see the following source files:
97+
98+
- **[`Source/`](https://github.com/CodeEditorLand/Air/tree/Current/Source/)** -
99+
Main daemon implementation
100+
- **[`Source/Update/`](https://github.com/CodeEditorLand/Air/tree/Current/Source/Update/)** -
101+
Update lifecycle management
102+
- **[`Source/Download/`](https://github.com/CodeEditorLand/Air/tree/Current/Source/Download/)** -
103+
Resilient download manager
104+
- **[`Source/Auth/`](https://github.com/CodeEditorLand/Air/tree/Current/Source/Auth/)** -
105+
Authentication and cryptographic signing
67106

68-
- **Pre-staged updates.** The next version is downloaded, PGP-verified, and
69-
ready before you decide to update.
70-
- **Pre-indexed workspaces.** File changes that happened while the editor was
71-
closed are already indexed.
72-
- **Warm language server caches.** IntelliSense is ready before you finish the
73-
first keystroke.
74-
- **No restart prompt.** Updates apply between sessions. You never see 'Restart
75-
to Update'.
107+
The source files explain the gRPC server implementation, task delegation from
108+
Mountain, and the progress event emission patterns.
76109

77110
---
78111

79-
## In the Ecosystem&#x2001;🪁 + 🏞️
112+
## System Architecture Diagram&#x2001;🏗️
113+
114+
This diagram illustrates how **Air** sits alongside `Mountain` to handle
115+
background operations.
80116

81117
```mermaid
82118
graph LR
@@ -117,18 +153,47 @@ graph LR
117153

118154
---
119155

120-
## Development&#x2001;🛠
156+
## `Air` in the Land Ecosystem&#x2001;🪁 + 🏞
121157

122-
Air is a component of the Land workspace. Follow the
123-
[Land Repository](https://github.com/CodeEditorLand/Land) instructions to build
124-
and run.
158+
| Component | Role \& Key Responsibilities |
159+
| :------------------ | :----------------------------------------------------------------------------------- |
160+
| **Daemon Process** | The persistent executable that runs independently of the main window. |
161+
| **Server Host** | Hosts a local server to accept commands from `Mountain` or other authorized clients. |
162+
| **Update Delegate** | The sole authority for modifying the installation files of the parent application. |
163+
| **Signer** | Handles cryptographic signing of artifacts and secure token storage for user login. |
164+
| **Traffic Manager** | Acts as a proxy/downloader to keep network load off the main renderer process. |
125165

126166
---
127167

128-
## License&#x2001;⚖️
168+
## Getting Started&#x2001;🚀
169+
170+
### Installation&#x2001;📥
171+
172+
To add `Air` to your project workspace:
173+
174+
```toml
175+
[dependencies]
176+
Air = { git = "https://github.com/CodeEditorLand/Air.git", branch = "Current" }
177+
```
178+
179+
### Usage Pattern&#x2001;🚀
180+
181+
**Air** is typically spawned automatically by `Mountain` during the startup
182+
phase.
183+
184+
1. **Spawn:** `Mountain` detects if `Air` is running. If not, it spawns the
185+
binary.
186+
2. **Connect:** `Mountain` establishes a Vine (gRPC) connection to `Air`'s local
187+
port `[::1]:50053` (reserved for Air, separate from Cocoon's port 50052).
188+
3. **Delegate:** When a user requests an update or a large download, `Mountain`
189+
sends a command to `Air` and immediately returns control to the user.
190+
4. **Monitor:** `Air` emits progress events back to `Mountain` to update the UI
191+
status bars.
129192

130-
CC0 1.0 Universal. Public domain. No restrictions.
131-
[LICENSE](https://github.com/CodeEditorLand/Air/tree/Current/LICENSE)
193+
### Port Allocation
194+
195+
- **Air**: Port `50053` (Vine/Air.proto protocol - Air daemon services)
196+
- **Cocoon**: Port `50052` (Vine.proto protocol - VS Code extension hosting)
132197

133198
---
134199

@@ -138,24 +203,30 @@ CC0 1.0 Universal. Public domain. No restrictions.
138203
- [Architecture Overview](https://editor.land/Doc/architecture)
139204
- [Why Rust](https://editor.land/Doc/why-rust)
140205
- [Mountain](https://github.com/CodeEditorLand/Mountain)
206+
- [Vine](https://github.com/CodeEditorLand/Vine)
141207
- [Echo](https://github.com/CodeEditorLand/Echo)
208+
- [Mist](https://github.com/CodeEditorLand/Mist)
209+
210+
---
142211

143-
## Changelog 📜
212+
## License&#x2001;⚖️
213+
214+
This project is released into the public domain under the **Creative Commons CC0
215+
Universal** license. You are free to use, modify, distribute, and build upon
216+
this work for any purpose, without any restrictions. For the full legal text,
217+
see the [`LICENSE`](https://github.com/CodeEditorLand/Air/tree/Current/) file.
218+
219+
---
220+
221+
## Changelog&#x2001;📜
144222

145223
Stay updated with our progress! See
146224
[`CHANGELOG.md`](https://github.com/CodeEditorLand/Air/tree/Current/) for a
147225
history of changes specific to **Air**.
148226

149227
---
150228

151-
## See Also
152-
153-
- [Architecture Overview](https://editor.land/Doc/architecture)
154-
- [Mountain](https://github.com/CodeEditorLand/Mountain)
155-
- [Vine](https://github.com/CodeEditorLand/Vine)
156-
- [Mist](https://github.com/CodeEditorLand/Mist)
157-
158-
## Funding \& Acknowledgements 🙏🏻
229+
## Funding \& Acknowledgements&#x2001;🙏🏻
159230

160231
**Air** is a core element of the **Land** ecosystem. This project is funded
161232
through [NGI0 Commons Fund](https://NLnet.NL/commonsfund), a fund established by

0 commit comments

Comments
 (0)