@sola-air-ui/relay 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +25 -8
  2. package/package.json +1 -1
  3. package/src/index.js +27 -9
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @sola-air-ui/relay
2
2
 
3
- A local data proxy for [Sola AIR](https://sola-air.dev)'s `createData`/`$data` primitive — keeps database credentials on your own machine (or server) instead of shipping them to the browser, and streams live query results to Sola components over a local connection.
3
+ A local data proxy for [Sola AIR](https://sola-air.dev)'s `createData`/`$data` primitive. It keeps database credentials on your own machine (or server) instead of shipping them to the browser, and answers Sola components' queries over a local HTTP endpoint.
4
4
 
5
5
  ## Install
6
6
 
@@ -8,35 +8,52 @@ A local data proxy for [Sola AIR](https://sola-air.dev)'s `createData`/`$data` p
8
8
  npm install @sola-air-ui/relay
9
9
  ```
10
10
 
11
+ ## Configure
12
+
13
+ The relay reads `sola-relay.json` from the directory you start it in. Each entry under `connections` is a name you choose plus its settings:
14
+
15
+ ```json
16
+ {
17
+ "connections": {
18
+ "postgres-primary": { "type": "postgres", "connectionString": "postgres://user:pass@localhost:5432/mydb" },
19
+ "orders-db": { "type": "mysql", "host": "localhost", "user": "reader", "password": "…", "database": "shop" }
20
+ }
21
+ }
22
+ ```
23
+
24
+ `postgres` settings go to `pg`'s `Pool`, and `mysql` settings to `mysql2`'s `createPool`. Give the relay a read-only database user.
25
+
11
26
  ## Run
12
27
 
13
28
  ```bash
14
- npx sola-relay --db postgres://user:pass@localhost:5432/mydb
29
+ npx sola-relay --port 4040
15
30
  ```
16
31
 
17
- By default this starts a local relay process that Sola's `createData()` calls connect to for real-time data sync — your Postgres/MySQL credentials never leave the process running the relay.
32
+ `--port` is the only option (default `4040`). The relay serves `POST /api/query`, `GET /api/schema?source=…` and `GET /api/status`, which lists each connection and whether it connected.
18
33
 
19
34
  ## Supported data sources
20
35
 
21
36
  - **PostgreSQL** (via `pg`)
22
37
  - **MySQL** (via `mysql2`)
23
- - Live updates pushed to connected clients over WebSocket (`ws`)
38
+ - **Google Sheets** (`type: "sheet"` with a `sheetId`): reads a sheet that is shared publicly, as CSV.
24
39
 
25
40
  ## Usage from a component
26
41
 
27
42
  ```html
28
43
  <script>
29
- let customers = $data('postgres-primary:customers', { sync: 'realtime' });
44
+ let customers = $data('postgres-primary:customers', { refresh: '30s' });
30
45
  </script>
31
46
 
32
- <Table rows={customers} />
47
+ <Table rows={() => customers().data} />
33
48
  ```
34
49
 
35
- `postgres-primary` refers to the connection alias configured when you start the relay — see `sola-relay --help` for connection/alias options.
50
+ The source is `connection:table`. `postgres-primary` is a name from `sola-relay.json`, and `customers` is a table in that database (`schema.table` works too). Connection names may use letters, digits, `_` and `-`. Table names must be plain identifiers, because they go into the query. With no `:table`, the connection name is used as the table name. `refresh` re-runs the query on that interval.
36
51
 
37
52
  ## Security note
38
53
 
39
- The relay is designed to run somewhere trusted (your dev machine, or a backend service you control) — never expose its port directly to the public internet without your own auth layer in front of it.
54
+ - SQL connections run a single read-only `SELECT`; anything else gets a 400.
55
+ - Every query is appended to `sola-relay-audit.log` in the working directory.
56
+ - The relay has no authentication of its own. Run it somewhere trusted (your dev machine, or a backend service you control), and never expose its port to the public internet without your own auth layer in front of it.
40
57
 
41
58
  ## License
42
59
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sola-air-ui/relay",
3
- "version": "1.0.3",
3
+ "version": "1.0.4",
4
4
  "description": "Sola Relay — local data proxy that keeps credentials on-device and streams live data to Sola components",
5
5
  "type": "module",
6
6
  "bin": {
package/src/index.js CHANGED
@@ -31,6 +31,18 @@ export function isReadOnlySql(sql) {
31
31
  return true;
32
32
  }
33
33
 
34
+ // A source is `connection` or `connection:table` (as in $data('pg-primary:customers')).
35
+ // The connection is a name from sola-relay.json. The table goes into SQL, so it must
36
+ // be a plain identifier, optionally schema-qualified; anything else is rejected.
37
+ // Without a table, the connection name doubles as the table name, as before.
38
+ const SOURCE_PATTERN = /^([A-Za-z0-9_-]+)(?::([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?))?$/;
39
+
40
+ export function parseSource(source) {
41
+ const m = typeof source === 'string' ? SOURCE_PATTERN.exec(source) : null;
42
+ if (!m) return null;
43
+ return { connection: m[1], table: m[2] ?? null };
44
+ }
45
+
34
46
  // ─── Connectors ───
35
47
  const connectors = new Map();
36
48
 
@@ -405,15 +417,16 @@ export class RelayServer {
405
417
  // ── Schema endpoint ──
406
418
  if (url.pathname === '/api/schema' && req.method === 'GET') {
407
419
  const source = url.searchParams.get('source');
408
- if (!source || !/^[a-zA-Z0-9_]+$/.test(source)) {
420
+ const parsedSource = parseSource(source);
421
+ if (!parsedSource) {
409
422
  res.writeHead(400, { 'Content-Type': 'application/json' });
410
423
  res.end(JSON.stringify({ error: 'Invalid source identifier' }));
411
424
  return;
412
425
  }
413
- const conn = connections.get(source);
426
+ const conn = connections.get(parsedSource.connection);
414
427
  if (!conn) {
415
428
  res.writeHead(404, { 'Content-Type': 'application/json' });
416
- res.end(JSON.stringify({ error: `Source '${source}' not found` }));
429
+ res.end(JSON.stringify({ error: `Source '${parsedSource.connection}' not found` }));
417
430
  return;
418
431
  }
419
432
  try {
@@ -447,23 +460,26 @@ export class RelayServer {
447
460
  const parsed = JSON.parse(body);
448
461
  const { source, query, limit } = parsed;
449
462
 
450
- if (!source || !/^[a-zA-Z0-9_]+$/.test(source)) {
463
+ const parsedSource = parseSource(source);
464
+ if (!parsedSource) {
451
465
  res.writeHead(400, { 'Content-Type': 'application/json' });
452
466
  res.end(JSON.stringify({ error: 'Invalid source identifier' }));
453
467
  return;
454
468
  }
469
+ const { connection } = parsedSource;
470
+ const table = parsedSource.table ?? connection;
455
471
 
456
- const conn = connections.get(source);
472
+ const conn = connections.get(connection);
457
473
 
458
474
  if (!conn) {
459
475
  res.writeHead(404, { 'Content-Type': 'application/json' });
460
- res.end(JSON.stringify({ error: `Source '${source}' not found` }));
476
+ res.end(JSON.stringify({ error: `Source '${connection}' not found` }));
461
477
  return;
462
478
  }
463
479
 
464
480
  if (conn.status !== 'connected') {
465
481
  res.writeHead(503, { 'Content-Type': 'application/json' });
466
- res.end(JSON.stringify({ error: `Source '${source}' is not connected` }));
482
+ res.end(JSON.stringify({ error: `Source '${connection}' is not connected` }));
467
483
  return;
468
484
  }
469
485
 
@@ -477,8 +493,10 @@ export class RelayServer {
477
493
 
478
494
  let result;
479
495
  if (isNonSql) {
496
+ const options = typeof query === 'object' && query !== null ? query : (query == null ? {} : { query });
480
497
  result = await conn.connector.query({
481
- ...(typeof query === 'object' && query !== null ? query : { query }),
498
+ ...(parsedSource.table && options.table == null ? { table: parsedSource.table } : {}),
499
+ ...options,
482
500
  limit: safeLimit
483
501
  });
484
502
  } else if (typeof query === 'object' && query !== null && typeof query.text === 'string') {
@@ -497,7 +515,7 @@ export class RelayServer {
497
515
  }
498
516
  result = await conn.connector.query(query);
499
517
  } else if (query == null) {
500
- result = await conn.connector.query(`SELECT * FROM ${source} LIMIT ${safeLimit}`);
518
+ result = await conn.connector.query(`SELECT * FROM ${table} LIMIT ${safeLimit}`);
501
519
  } else {
502
520
  res.writeHead(400, { 'Content-Type': 'application/json' });
503
521
  res.end(JSON.stringify({ error: 'Only SELECT queries are permitted' }));