Skip to content

Commit 5f8b2ea

Browse files
NikolaRHristovNikolaRHristov
committed
1 parent 7ee0219 commit 5f8b2ea

64 files changed

Lines changed: 15153 additions & 7820 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 219 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -46,22 +46,170 @@ SideCar/
4646

4747
### How It's Used
4848

49-
The `Download.sh` script in this directory is responsible for populating this
50-
structure. It fetches the official distributions for various sidecars and
51-
platforms and organizes them according to the convention above.
49+
The [`Download`](Source/Download.rs) Rust binary in this directory is
50+
responsible for populating this structure. It fetches the official distributions
51+
for various sidecars and platforms and organizes them according to the
52+
convention above.
53+
54+
The download tool provides:
55+
56+
- **Concurrent Downloads**: Parallel downloading of multiple binaries using
57+
Tokio
58+
- **Intelligent Caching**: Maintains a [`Cache.json`](Cache.json) file to track
59+
downloaded versions
60+
- **Version Resolution**: Automatically resolves major versions to latest patch
61+
from nodejs.org
62+
- **Git LFS Management**: Automatically updates
63+
[`.gitattributes`](.gitattributes) for large binary tracking
64+
- **Platform Matrix**: Supports multiple target triples (x86_64, aarch64 for
65+
macOS, Linux, Windows)
5266

5367
During the application build, the main `Build.rs` orchestrator uses this
5468
repository as a source. Based on build flags (e.g., `--node-version=22`), it
5569
selects the appropriate executable from this directory and prepares it for
5670
bundling into the final application installer.
5771

72+
---
73+
74+
## Key Features 🔐
75+
76+
- **Concurrent Downloads:** Parallel downloading of multiple runtime binaries
77+
using Tokio for maximum throughput.
78+
- **Intelligent Caching:** Maintains a `Cache.json` file to track downloaded
79+
versions and avoid redundant downloads.
80+
- **Version Resolution:** Automatically resolves major versions to latest patch
81+
from nodejs.org and other sources.
82+
- **Git LFS Management:** Automatic `.gitattributes` updates for large binary
83+
tracking in Git LFS.
84+
- **Platform Matrix:** Comprehensive support for x86_64 and aarch64
85+
architectures across macOS, Linux, and Windows.
86+
87+
---
88+
89+
## Core Architecture Principles 🏗️
90+
91+
| Principle | Description | Key Components Involved |
92+
| :-------------------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------- |
93+
| **Deterministic Selection** | Organize binaries by target triple for deterministic build-time selection. | Directory structure, target triple convention |
94+
| **Version Tracking** | Maintain cache metadata to avoid redundant downloads and ensure version consistency. | `Cache.json`, version resolution |
95+
| **Git LFS Integration** | Automatically manage Git LFS pointers for large binary tracking. | `.gitattributes` management |
96+
97+
---
98+
99+
## `SideCar` in the Land Ecosystem ⚙️ + 🏞️
100+
101+
| Component | Role & Key Responsibilities |
102+
| :---------------- | :-------------------------------------------------------------------- |
103+
| **Download Tool** | Populates the SideCar directory with pre-compiled runtime binaries. |
104+
| **Cache Manager** | Tracks downloaded versions in `Cache.json` for build reproducibility. |
105+
| **Build Source** | Provides vendored runtimes to `Mountain` during the build process. |
106+
107+
---
108+
109+
## Getting Started 🚀
110+
111+
### Running the Download Tool
112+
113+
```sh
114+
# Build the download tool
115+
cd Element/SideCar
116+
cargo build --release
117+
118+
# Run to download and organize all sidecars
119+
./Target/release/Download
120+
```
121+
122+
**Key Dependencies:**
123+
124+
- `tokio`: Async runtime for concurrent downloads
125+
- `reqwest`: HTTP client for fetching binaries
126+
- `serde`/`serde_json`: Cache.json serialization
127+
- `git2`: Git LFS management
128+
129+
### Usage Pattern
130+
131+
The SideCar directory is populated once during project setup:
132+
133+
1. **Build Download Tool:** Compile the `Download` binary
134+
2. **Run Download:** Execute to fetch and organize all runtime binaries
135+
3. **Build Mountain:** The build system selects appropriate binaries from
136+
SideCar
137+
58138
> [!NOTE]
59139
>
60-
> The contents of this directory are generated by the `Download.sh` script and
61-
> consist of large, third-party binaries. This directory **should not be
62-
> committed to version control** and should be added to the project's
63-
> `.gitignore` file. The script should be run once to vendor the dependencies as
64-
> part of the initial project setup.
140+
> The contents of this directory are generated by the
141+
> [`Download`](Source/Download.rs) Rust binary and consist of large, third-party
142+
> binaries. This directory **should not be committed to version control** and
143+
> should be added to the project's `.gitignore` file. The tool should be run
144+
> once to vendor the dependencies as part of the initial project setup.
145+
>
146+
> ### Running the Download Tool
147+
>
148+
> ```sh
149+
> # Build the download tool
150+
> cd Element/SideCar
151+
> cargo build --release
152+
>
153+
> # Run to download and organize all sidecars
154+
> ./Target/release/Download
155+
> ```
156+
157+
---
158+
159+
## System Architecture Diagram 🏗️
160+
161+
This diagram illustrates how `SideCar` vendors and organizes runtime
162+
dependencies.
163+
164+
```mermaid
165+
graph LR
166+
classDef sidecar fill:#f9f,stroke:#333,stroke-width:2px;
167+
classDef external fill:#ddd,stroke:#666,stroke-dasharray: 5 5;
168+
classDef storage fill:#9cf,stroke:#333,stroke-width:1px;
169+
170+
subgraph "External Sources"
171+
NodeJSOrg["nodejs.org"]:::external
172+
OtherRuntimes["Other Runtime Sources"]:::external
173+
end
174+
175+
subgraph "SideCar ⚙️ (Download Tool)"
176+
DownloadBin["Download Binary"]:::sidecar
177+
CacheJSON["Cache.json"]:::sidecar
178+
GitLFS[".gitattributes (LFS)"]:::sidecar
179+
180+
DownloadBin --> CacheJSON
181+
DownloadBin --> GitLFS
182+
end
183+
184+
subgraph "SideCar Directory Structure"
185+
TargetTriple["[target-triple]/"]:::storage
186+
RuntimeName["[SIDECAR_NAME]/"]:::storage
187+
Version["[version]/bin/"]:::storage
188+
189+
TargetTriple --> RuntimeName
190+
RuntimeName --> Version
191+
end
192+
193+
NodeJSOrg --> DownloadBin
194+
OtherRuntimes --> DownloadBin
195+
DownloadBin --> TargetTriple
196+
```
197+
198+
---
199+
200+
## Deep Dive & Component Breakdown 🔬
201+
202+
To understand how `SideCar`'s download tool works, see the following source
203+
files:
204+
205+
- **[`Source/Download.rs`](Source/Download.rs)** - Main download binary entry
206+
point
207+
- **[`Cache.json`](Cache.json)** - Download cache tracking file
208+
- **[[`.gitattributes`](.gitattributes)](.gitattributes)** - Git LFS
209+
configuration for large binaries
210+
211+
The download tool handles concurrent downloads, version resolution from
212+
nodejs.org, and automatic Git LFS management for tracking large binary files.
65213

66214
---
67215

@@ -70,14 +218,71 @@ bundling into the final application installer.
70218
| **Related Directory**:
71219
[`Binary`](https://github.com/CodeEditorLand/Mountain/tree/Current/Binary/README.md)
72220

73-
## Funding
221+
## License ⚖️
222+
223+
This project is released into the public domain under the **Creative Commons CC0
224+
Universal** license. You are free to use, modify, distribute, and build upon
225+
this work for any purpose, without any restrictions. For the full legal text,
226+
see the [`LICENSE`](https://github.com/CodeEditorLand/SideCar/tree/Current/)
227+
file.
228+
229+
---
230+
231+
## Changelog 📜
74232

75-
This project is funded through
76-
[NGI0 Commons Fund](https://NLnet.NL/commonsfund), a fund established by
233+
Stay updated with our progress! See
234+
[`CHANGELOG.md`](https://github.com/CodeEditorLand/SideCar/tree/Current/) for a
235+
history of changes specific to **SideCar**.
236+
237+
---
238+
239+
## Funding & Acknowledgements 🙏🏻
240+
241+
**SideCar** is a core element of the **Land** ecosystem. This project is funded
242+
through [NGI0 Commons Fund](https://NLnet.NL/commonsfund), a fund established by
77243
[NLnet](https://NLnet.NL) with financial support from the European Commission's
78244
[Next Generation Internet](https://ngi.eu) program. Learn more at the
79245
[NLnet project page](https://NLnet.NL/project/Land).
80246

81-
| Land | PlayForm | NLnet | NGI0 Commons Fund |
82-
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
83-
| [<img src="https://raw.githubusercontent.com/CodeEditorLand/Asset/refs/heads/Current/Logo/Land.svg" height="80px" alt="Land" />](https://Editor.Land) | [<img src="https://raw.githubusercontent.com/PlayForm/Asset/refs/heads/Current/Logo/PlayForm.svg" height="80px" alt="PlayForm" />](https://PlayForm.Cloud) | [<img width="240px" src="https://NLnet.NL/logo/banner.svg" alt="NLnet" />](https://NLnet.NL) | [<img width="240px" src="https://NLnet.NL/image/logos/NGI0CommonsFund_tag_black_mono.svg" alt="NGI0 Commons Fund" />](https://NLnet.NL/commonsfund) |
247+
<table>
248+
<thead>
249+
<tr>
250+
<th align="left"><strong>Land</strong></th>
251+
<th align="left"><strong>PlayForm</strong></th>
252+
<th align="left"><strong>NLnet</strong></th>
253+
<th align="left"><strong>NGI0 Commons Fund</strong></th>
254+
</tr>
255+
</thead>
256+
<tbody>
257+
<tr>
258+
<td align="left" valign="middle">
259+
<a href="https://Editor.Land">
260+
<img width="60" src="https://raw.githubusercontent.com/CodeEditorLand/Asset/refs/heads/Current/Logo/Land.svg" alt="Land">
261+
</a>
262+
</td>
263+
<td align="left" valign="middle">
264+
<a href="https://PlayForm.Cloud">
265+
<img width="76" src="https://raw.githubusercontent.com/PlayForm/Asset/refs/heads/Current/Logo/PlayForm.svg" alt="PlayForm">
266+
</a>
267+
</td>
268+
<td align="left" valign="middle">
269+
<a href="https://NLnet.NL">
270+
<img width="240" src="https://NLnet.NL/logo/banner.svg" alt="NLnet">
271+
</a>
272+
</td>
273+
<td align="left" valign="middle">
274+
<a href="https://NLnet.NL/commonsfund">
275+
<img width="240" src="https://NLnet.NL/image/logos/NGI0CommonsFund_tag_black_mono.svg" alt="NGI0 Commons Fund">
276+
</a>
277+
</td>
278+
</tr>
279+
</tbody>
280+
</table>
281+
282+
---
283+
284+
**Project Maintainers**: Source Open
285+
([Source/Open@Editor.Land](mailto:Source/Open@Editor.Land)) |
286+
[GitHub Repository](https://github.com/CodeEditorLand/SideCar) |
287+
[Report an Issue](https://github.com/CodeEditorLand/SideCar/issues) |
288+
[Security Policy](https://github.com/CodeEditorLand/SideCar/security/policy)

‎SECURITY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ not limited to):**
5959
- **Denial of Service (DoS):** If an Element can be made unresponsive or crash
6060
due to specially crafted input or excessive resource consumption.
6161
- **Path Traversal/Arbitrary File Access:** For Elements interacting with the
62-
filesystem (like `Mountain`'s FS handlers), ensuring that
63-
path inputs are properly sanitized.
62+
filesystem (like `Mountain`'s FS handlers), ensuring that path inputs are
63+
properly sanitized.
6464
- **Insecure IPC/Communication:** For Elements involved in inter-process
6565
communication (`Vine`, `Track`, `Echo`, `Mist`), vulnerabilities in the
6666
protocol or handling of messages.

‎aarch64-apple-darwin/NODE/16/CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5456,7 +5456,7 @@ import assertions are now required to import JSON modules (still behind the
54565456
`--experimental-json-modules` CLI flag):
54575457

54585458
```mjs
5459-
import info from "./package.json" assert { type: "json" };
5459+
import info from "./package.json" with { type: "json" };
54605460
```
54615461

54625462
Or use dynamic import:

‎aarch64-apple-darwin/NODE/16/README.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@ Node.js is an open-source, cross-platform JavaScript runtime environment.
44

55
For information on using Node.js, see the [Node.js website][].
66

7-
The Node.js project uses an [open governance model](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/GOVERNANCE.md). The
8-
[OpenJS Foundation][] provides support for the project.
7+
The Node.js project uses an
8+
[open governance model](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/GOVERNANCE.md).
9+
The [OpenJS Foundation][] provides support for the project.
910

1011
**This project has a [Code of Conduct][].**
1112

@@ -126,8 +127,10 @@ signature.
126127

127128
## Building Node.js
128129

129-
See [BUILDING.md](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/BUILDING.md) for instructions on how to build Node.js from
130-
source and a list of supported platforms.
130+
See
131+
[BUILDING.md](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/BUILDING.md)
132+
for instructions on how to build Node.js from source and a list of supported
133+
platforms.
131134

132135
## Security
133136

@@ -632,8 +635,8 @@ For information about the governance of the Node.js project, see
632635
<!--lint enable prohibited-strings-->
633636

634637
Collaborators follow the
635-
[Collaborator Guide](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/doc/contributing/collaborator-guide.md) in maintaining
636-
the Node.js project.
638+
[Collaborator Guide](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/16/doc/contributing/collaborator-guide.md)
639+
in maintaining the Node.js project.
637640

638641
### Triagers
639642

‎aarch64-apple-darwin/NODE/17/README.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@ Node.js is an open-source, cross-platform, JavaScript runtime environment.
44

55
For information on using Node.js, see the [Node.js website][].
66

7-
The Node.js project uses an [open governance model](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/GOVERNANCE.md). The
8-
[OpenJS Foundation][] provides support for the project.
7+
The Node.js project uses an
8+
[open governance model](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/GOVERNANCE.md).
9+
The [OpenJS Foundation][] provides support for the project.
910

1011
**This project has a [Code of Conduct][].**
1112

@@ -126,8 +127,10 @@ signature.
126127

127128
## Building Node.js
128129

129-
See [BUILDING.md](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/BUILDING.md) for instructions on how to build Node.js from
130-
source and a list of supported platforms.
130+
See
131+
[BUILDING.md](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/BUILDING.md)
132+
for instructions on how to build Node.js from source and a list of supported
133+
platforms.
131134

132135
## Security
133136

@@ -611,8 +614,8 @@ For information about the governance of the Node.js project, see
611614
<!--lint enable prohibited-strings-->
612615

613616
Collaborators follow the
614-
[Collaborator Guide](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/doc/contributing/collaborator-guide.md) in maintaining
615-
the Node.js project.
617+
[Collaborator Guide](https://github.com/CodeEditorLand/SideCar/tree/Current/aarch64-apple-darwin/NODE/17/doc/contributing/collaborator-guide.md)
618+
in maintaining the Node.js project.
616619

617620
### Triagers
618621

0 commit comments

Comments
 (0)