Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions electron-app/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,62 @@ sudo ifconfig lo0 alias 127.0.0.9 up

- **Mode Selector**: html5 file to chose the mode of the app: testing, competition or flashing. Placed at `renderer/mode-selector`

## Cloud Logs

Cloud Logs is a desktop capability shared by Logging View and Testing View. The
renderer calls the narrow `window.electronAPI.cloudLogs` interface exposed from
`preload.js`; it does not access the filesystem, ZIP library, credentials, or
remote API directly. The IPC handlers in `src/cloudLogs/handlers.js` validate
that requests come from the local Logging or Testing window and keep local paths
inside the Electron main process.

The local folder format is `<logging_path>/logger/<app-launch>/<recording>/`.
Cloud uploads operate on one recording at a time. A recording ZIP contains the
root `logger_settings.json` and the supported CSV subfolders (`data`, `order`,
`protections`/`protection`, and `state`). Launcher traces and unrelated files
are excluded. The date attached to a cloud record comes from the recording's
`logger_settings.json`, not from the time it was uploaded. Users must confirm
that recording has stopped; Electron checks that its files did not change while
it compressed the ZIP and reports compression progress to the requesting view.

Downloaded archives are checked and extracted into
`<logging_path>/logger/cloud-logs/<sha256-cloud-id>/`. Extraction uses a staging
directory and rejects unsafe paths, links, duplicate entries, unsupported files,
encrypted ZIPs, and archives over the configured file and byte limits. Logging
View opens a downloaded recording through the same loader it uses for local
folders, so analysis works offline after download. `cloud-logs/` is created on
first use, even when the Go backend is not running.

The shared typed renderer contract is exported as `CloudLogsAPI` from
`@hyperloopupv/frontend-kit/core`. Testing View already has that type on its
Electron bridge, so it can call the same service without implementing another
network or filesystem client. The React implementation currently lives in
`frontend/logging-view/src/components/cloudLogs/CloudLogsDialog.tsx`.

Credentials are entered in the Cloud Logs dialog and managed by Electron in
`src/cloudLogs/credentials.js`. The user name and encrypted key are stored in
`<Electron userData>/cloud-logs.json` when OS secure storage is available. If
secure storage is unavailable, Electron keeps the key in memory until exit. The
key is never sent back to the renderer; the renderer only receives the user,
whether a key is configured, and whether storage is persistent.

### Connecting the Cloud Logs API

The remote API is intentionally not assumed. Its only integration boundary is
`src/cloudLogs/client.js`; the four functions there currently reject with a
clear not-connected error. Implement `listLogs`, `autocompleteTags`, `uploadLog`,
and `downloadLog` there after confirming endpoint URLs, authentication format,
pagination, multipart field names, and response shapes with the API owner.
Normalize returned records to `{ id, user, notes, tags, date }`, stream ZIPs to
and from disk, enforce download limits while streaming, and sanitize errors so
they never include credentials. The request and security details are recorded in
`src/cloudLogs/README.md` next to the service implementation.

While the client remains a placeholder, local session discovery, ZIP creation,
credential management, download validation, and the UI are usable, but browsing
cloud records, tag suggestions, uploads, and downloads report that the API is
not connected. There are no mocked cloud results or false success states.

## Dependencies

- `electron` - Desktop application framework
Expand Down
6 changes: 4 additions & 2 deletions electron-app/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"type": "module",
"author": {
"name": "Hyperloop UPV",
"email": "partners@hyperloopupv.com"
"email": "software@hyperloopupv.com"
},
"contributors": [
{
Expand Down Expand Up @@ -66,9 +66,11 @@
"dependencies": {
"@iarna/toml": "^2.2.5",
"ansi-to-html": "^0.7.2",
"archiver": "5.3.2",
"electron-store": "^11.0.2",
"electron-updater": "^6.7.3",
"picocolors": "^1.1.1"
"picocolors": "^1.1.1",
"yauzl": "2.10.0"
},
"devDependencies": {
"@vitest/coverage-v8": "^4.0.18",
Expand Down
17 changes: 17 additions & 0 deletions electron-app/preload.js
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,23 @@ const { contextBridge, ipcRenderer } = require("electron");
* await window.electronAPI.saveConfig({ database: { host: "localhost" } });
*/
contextBridge.exposeInMainWorld("electronAPI", {
cloudLogs: {
getCredentialsStatus: () => ipcRenderer.invoke("cloud-logs:credentials-status"),
setCredentials: (input) => ipcRenderer.invoke("cloud-logs:credentials-save", input),
clearCredentials: () => ipcRenderer.invoke("cloud-logs:credentials-clear"),
getLocalSessions: () => ipcRenderer.invoke("cloud-logs:local-sessions"),
selectSession: () => ipcRenderer.invoke("cloud-logs:select-session"),
list: (cursor) => ipcRenderer.invoke("cloud-logs:list", cursor),
autocompleteTags: (query) => ipcRenderer.invoke("cloud-logs:tags", query),
upload: (input) => ipcRenderer.invoke("cloud-logs:upload", input),
download: (input) => ipcRenderer.invoke("cloud-logs:download", input),
getDownloads: () => ipcRenderer.invoke("cloud-logs:downloads"),
onProgress: (callback) => {
const listener = (_event, progress) => callback(progress);
ipcRenderer.on("cloud-logs:progress", listener);
return () => ipcRenderer.removeListener("cloud-logs:progress", listener);
},
},
// Get the currently loaded view name
getCurrentView: () => ipcRenderer.invoke("get-current-view"),
// Switch to a different view by name, optionally passing query params
Expand Down
112 changes: 112 additions & 0 deletions electron-app/src/cloudLogs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Cloud Logs integration

Desktop service shared by Logging View and Testing View via
`window.electronAPI.cloudLogs`. The typed contract is exported from
`@hyperloopupv/frontend-kit/core` (`CloudLogsAPI`). React never imports Node code.

## File map

| File | Responsibility | Change it when… |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `client.js` | The remote HTTP adapter. Defines list, tag suggestions, upload, and ZIP download functions; currently these are explicit not-connected placeholders. | Implementing API endpoints, authentication, pagination, request fields, or response mapping. |
| `credentials.js` | Reads, writes, encrypts, and clears the Cloud Logs user and API key. Only credential status is returned to the renderer. | Changing credential persistence, secure-storage policy, or validation. |
| `sessions.js` | Resolves the configured `logger/` root, creates `cloud-logs/`, scans local launch folders, and validates a recording using its `logger_settings.json`. | Changing how backend recordings are laid out or what qualifies as a session. |
| `archive.js` | Zips every regular file inside one recording and safely extracts downloaded archives. Reports compression and extraction progress. | Changing archive layout, ZIP safety checks, limits, or progress. |
| `handlers.js` | Connects renderer IPC calls to credentials, session discovery, archive operations, and the remote adapter. Checks the calling window, owns local path grants, scopes progress, and removes temporary files. | Adding renderer operations, changing authorization, or coordinating uploads and downloads. |
| `__tests__/storage.test.js` | Tests local session discovery, ZIP round trips and safety, arbitrary logger subfolders, and credential storage using temporary files. It does not call the remote API. | Adding regression coverage for session storage, ZIP handling, or credentials. |
| `README.md` | This module guide and API handoff contract. | Updating module behavior or integration instructions. |

Related bridge files live outside this directory: `electron-app/preload.js`
exposes `window.electronAPI.cloudLogs`; `frontend/frontend-kit/kit/src/core/cloudLogs.ts`
defines the shared TypeScript contract; and
`frontend/logging-view/src/components/cloudLogs/CloudLogsDialog.tsx` implements
the Logging View dialog. Testing View can use the same preload bridge and types.

## Remote API: teammate handoff

**Only `client.js` is a placeholder.** Implement its four async functions:

| Function | Input | Result |
| ------------------ | ------------------------------------------- | ---------------------------------------------- |
| `listLogs` | credentials, optional cursor | `{ items: CloudLog[], nextCursor?: string }` |
| `autocompleteTags` | credentials, query (including empty string) | `string[]` |
| `uploadLog` | credentials, archivePath, metadata | confirmed `CloudLog` |
| `downloadLog` | credentials, id, destination, maxBytes | resolves after ZIP is fully written and closed |

`CloudLog` has `{ id, user, notes, tags: string[], date }`. Normalize the remote
API's response to this contract; for example map a `description` field to `notes`.
The log date is the original `logger_settings.json.date`, not the upload date.
It may have the backend's `YYYY-MM-DDTHH-mm-ss` format; document any conversion
required by the remote API without inventing a timezone for these local dates.

Supply the endpoint URLs and authentication header/form fields according to the
real API contract; none are assumed here. Validate responses, bound request time,
and return useful sanitized errors (no API key, headers or raw request dumps).
Stream files instead of loading entire ZIPs into RAM. Enforce `maxBytes` while
downloading, even without Content-Length. Never forward authentication headers
to unrelated download/redirect origins. Do not blindly retry uploads unless the
API supports idempotency.

The stubs deliberately reject with an explicit "API is not connected" error.
There are no fake tags, cloud records or successful uploads. With configured
credentials, pressing upload really compresses the session and reports progress,
then reaches the upload stub. Temporary ZIPs are removed even on failure.

## Local service (implemented)

- Local discovery: `<logging_path>/logger/<app-launch>/<recording>/`.
- Native folder selection also permits recordings outside that root. The main
process gives the renderer an opaque token scoped to its window, not a generic
"upload any path" API.
- One recording per ZIP. `logger_settings.json` stays at the ZIP root, and every
regular file inside that recording is included, even in unrecognized or future
subfolders such as `orders/`, `protections/`, and `other/`. The parent app
launch folder is never archived. The local `cloud-log.json` download marker is
excluded. Upload only stopped recordings; compression rejects files whose
size/mtime or membership changes during archiving.
- Upload ZIPs are created as `session.zip` inside an OS temporary directory named
`cloud-logs-upload-*` (under Node's `os.tmpdir()`). Electron deletes that
directory after the upload completes or fails; the ZIP is not retained.
- `logger/cloud-logs/` is created on first use, also with the Go backend stopped.
Paths resolve against the same backend working directory and `logging_path`.
`others/` remains inside each app launch, not beside the launch folders.
- Downloads extract into a private `.download-*` staging directory. After
validation they are renamed into `cloud-logs/<sha256(remote-id)>/`. Hashing the
ID avoids platform-invalid names and collisions from sanitizing IDs.
- The downloaded ZIP is temporarily named `session.zip` inside that staging
directory. After extraction succeeds or fails, Electron removes the staging
directory and ZIP; only the validated extracted session is kept.
- `cloud-log.json` stores the original ID and date beside the extracted session.
Repeated downloads reuse a valid local copy. Staging files are removed on error;
incomplete directories are excluded from the offline library.
- Extraction rejects traversal, symlinks, encrypted archives, duplicate file
entries and oversized archives. It accepts arbitrary regular files in a
downloaded recording so future logger subfolders remain usable. Limits: 4 GiB
and 10,000 entries.
- Progress is scoped by requestId and sent only to the requesting window.
Compression and extraction report file progress; network phases are
indeterminate. One transfer at a time across the desktop app. The dialog stays
open during transfers; closing the application still interrupts them.

## Credentials

`<Electron userData>/cloud-logs.json` holds the user and encrypted API key. With
no secure OS storage (including Linux `basic_text`/`unknown`), only the user is
persisted; the key stays in process memory. No key is returned to React. Blank
key on save preserves the current key; removing credentials requires the
explicit Remove action. Credentials updates are serialized across windows.

## UI and future consumers

Logging View's sidebar opens Library / Upload / Credentials. Tags are fetched
with a debounced API search. Recording date is read-only and comes from the
selected recording. Downloads open through the existing session-folder loader,
so CSV parsing, charts and recent sessions keep the same behavior. In a browser
without Electron the dialog explains that desktop integration is required.

Testing View can call the same bridge; its global interface already includes
`cloudLogs`. No backend lifecycle changes are required for cloud operations.

Run `pnpm --dir electron-app test -- src/cloudLogs/__tests__` and the Logging
View build/lint. The tests use real temporary files and ZIPs, mocked credentials
storage and no remote network.
Loading
Loading