pgkiln 0.73.0 → 0.75.0

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 (53) hide show
  1. package/db/migrations/141_workspace_resources.sql +115 -0
  2. package/db/migrations/142_json_sources.sql +426 -0
  3. package/docs/apex-feature-parity.md +11 -8
  4. package/docs/guide/01-installation.md +1 -0
  5. package/docs/guide/03-builder.md +62 -4
  6. package/docs/guide/04-pages-and-regions.md +1 -0
  7. package/docs/guide/12-development.md +26 -1
  8. package/docs/guide/16-files.md +29 -0
  9. package/docs/guide/19-rest-data-sources.md +149 -4
  10. package/examples/hr/hr_76_remote_servers.sql +48 -0
  11. package/examples/hr/hr_77_json_sources.sql +174 -0
  12. package/package.json +1 -1
  13. package/src/ai/service.ts +10 -1
  14. package/src/app.ts +7 -0
  15. package/src/builder/advisor.ts +13 -1
  16. package/src/builder/ai.ts +29 -3
  17. package/src/builder/designer.ts +1 -1
  18. package/src/builder/document-view.ts +117 -0
  19. package/src/builder/home.ts +3 -0
  20. package/src/builder/i18n/de.ts +1 -0
  21. package/src/builder/i18n/en.ts +1 -0
  22. package/src/builder/i18n/es.ts +1 -0
  23. package/src/builder/i18n/fr.ts +1 -0
  24. package/src/builder/i18n/it.ts +1 -0
  25. package/src/builder/i18n/ja.ts +1 -0
  26. package/src/builder/i18n/ko.ts +1 -0
  27. package/src/builder/i18n/nl.ts +1 -0
  28. package/src/builder/i18n/pt.ts +1 -0
  29. package/src/builder/i18n/zh-cn.ts +1 -0
  30. package/src/builder/i18n/zh-tw.ts +1 -0
  31. package/src/builder/json-sources.ts +395 -0
  32. package/src/builder/network-access.ts +33 -0
  33. package/src/builder/object-actions.ts +1 -0
  34. package/src/builder/report-settings.ts +9 -0
  35. package/src/builder/rest-catalogs.ts +22 -14
  36. package/src/builder/routes.ts +5 -1
  37. package/src/builder/shared.ts +1 -1
  38. package/src/builder/static-files.ts +14 -4
  39. package/src/builder/table-editor.ts +1 -0
  40. package/src/builder/websources.ts +18 -9
  41. package/src/builder/workflows.ts +2 -1
  42. package/src/builder/workspace-resources.ts +528 -0
  43. package/src/json-sources.ts +365 -0
  44. package/src/metadata.ts +17 -3
  45. package/src/remote-servers.ts +133 -0
  46. package/src/restcatalog.ts +21 -10
  47. package/src/restsync.ts +1 -1
  48. package/src/runtime/context.ts +2 -0
  49. package/src/runtime/report.ts +3 -1
  50. package/src/runtime/static-files.ts +46 -17
  51. package/src/runtime/template-components.ts +2 -1
  52. package/src/websources.ts +43 -18
  53. package/src/workspace-export.ts +80 -1
@@ -15,7 +15,8 @@ Web Credentials and the Invoke API process):
15
15
  puts values of the response into items; the **`invoke_api` workflow step** does the same on the
16
16
  server, with workflow variables ([chapter 6](06-processing.md#invoke-api-steps)).
17
17
 
18
- Both are **Shared Components**. The server only calls hosts its administrator allows
18
+ Both are **Shared Components**, as are **JSON sources** ([below](#json-sources-and-document-views)): forms,
19
+ reports and grids over the documents in a `jsonb` column of your own tables. The server only calls hosts its administrator allows
19
20
  ([below](#server-configuration-and-the-allow-list)): out of the box, no outgoing request is made.
20
21
 
21
22
  Try it with the HR example: page 23 "Web services" reads the HR example's own REST module
@@ -84,6 +85,12 @@ Shared Components → **Web credentials** → + Add.
84
85
  | OAuth2 password, Refresh token | `oauth2`: the password of the OAuth2 user (`password` grant), or a refresh token obtained elsewhere (`refresh_token` grant). Write-only like the secret, each with its own **Remove** button |
85
86
  | Valid for URLs | URL prefixes the credential may be sent to, e.g. `https://api.example.com/v2/`. Recommended: a source or process that points elsewhere fails instead of sending the secret |
86
87
 
88
+ **Workspace web credentials** (sprint 141): Workspace utilities → **Web credentials** holds credentials with the same
89
+ properties for every application of the workspace ([chapter 3](03-builder.md#static-workspace-files-remote-servers-and-web-credentials)).
90
+ Wherever a credential is named (a source, the `invoke_api` process and step, `meta.web_request`, a remote server's
91
+ default credential, object storage), the application's own credential of that name is used, else the workspace's.
92
+ Another workspace's credentials are never found.
93
+
87
94
  For `oauth2`, pgkiln asks the token endpoint for an access token, keeps it until 30 seconds before
88
95
  it expires, renews it with the refresh token when the endpoint gave one, and asks for a new one when
89
96
  the service answers 401. Access tokens are kept in the server's memory only.
@@ -118,9 +125,10 @@ Shared Components → **REST data sources** → + Add.
118
125
  | Property | Meaning |
119
126
  |---|---|
120
127
  | Name | Uppercase, e.g. `COUNTRIES` |
121
- | URL | `https://api.example.com/v1/cities/{city}/weather`: `{name}` is a path parameter. The host is fixed: parameters can only come after it |
128
+ | Remote server | Optional (sprint 141): a [remote server](#remote-servers) of the workspace, e.g. `CRM`; the URL is then the path after its base URL |
129
+ | URL | `https://api.example.com/v1/cities/{city}/weather`: `{name}` is a path parameter. The host is fixed: parameters can only come after it. With a remote server: `/v1/cities/{city}/weather` |
122
130
  | Method | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
123
- | Web credential | The name of a web credential, or empty |
131
+ | Web credential | The name of a web credential (the application's, else the workspace's), or empty: on a remote server, the server's default credential |
124
132
  | Parameters | JSON: `[{"name": "city", "in": "path", "default": "&P1_CITY.", "required": true}, {"name": "units", "in": "query", "default": "metric"}]`. `in` is `path`, `query`, `header` or `body`. Defaults may use `&ITEM.` substitutions. `key`: the service's own name for a query, header or body parameter when it isn't lower case with `_`, e.g. `{"name": "page_size", "in": "query", "key": "pageSize"}`; `Authorization`, `Cookie`, `Host` and the transport headers can't be header parameters |
125
133
  | Headers | JSON: extra request headers, e.g. `{"Accept-Language": "en"}`. Not for secrets (use a web credential); `Authorization`, `Cookie`, `Host` and the transport headers can't be set |
126
134
  | Body | For `POST`, `PUT`, `PATCH`: a JSON template, `{name}` becomes the parameter's value as a JSON string. Empty: the `body` parameters as a JSON object |
@@ -143,6 +151,30 @@ call; define them so reports keep their columns when the service changes.
143
151
  Path parameters are URL-encoded (`.` and `..` are refused), query parameters appended, header
144
152
  parameters sent as headers (one line only), so a value from an item can never change the host.
145
153
 
154
+ ### Remote servers
155
+
156
+ A **remote server** (sprint 141; APEX: Remote Servers) is a named base URL of the workspace, kept under Workspace
157
+ utilities → **Remote servers** ([chapter 3](03-builder.md#static-workspace-files-remote-servers-and-web-credentials)):
158
+ a static id (`CRM`), this installation's base URL (`http://127.0.0.1:3100`) and/or an environment variable
159
+ `PGKILN_SERVER_CRM` that wins when set, and an optional default web credential. A source on a server keeps only its
160
+ path (`/a/hr/rest/v1/departments`); every call uses the server's URL **of that moment**, so changing the server (or
161
+ setting `PGKILN_SERVER_CRM=https://crm.example.com` on the production server) moves every source on it at once,
162
+ including write-back, synchronisation, the builder's *Test* and `invoke_api`.
163
+
164
+ - The resolved URL passes every check a full URL does: the allow-list, the workspace's
165
+ [network access list](03-builder.md#network-access) (whose page lists each server's host) and the address checks
166
+ when the connection is made. A server pointed at a private address is refused unless the installation allows it.
167
+ - The path is a path: it starts with `/` or `?` (or is empty), with no `//` or `..` segments, so it can't name another
168
+ host.
169
+ - A server that doesn't exist in the application's workspace fails the call with *Remote server X does not exist in
170
+ this application's workspace*. An application export names the server; it imports where the server is missing, and
171
+ the import message and the [Advisor](03-builder.md#advisor) (a warning) name it.
172
+ - A [REST source catalog](#rest-source-catalogs) can be on a server too, and so can an
173
+ [AI service](03-builder.md#ai-services).
174
+
175
+ HR example (part 76): server **CRM** stands for the HR API on `http://127.0.0.1:3100`; DEPARTMENTS, DEPARTMENT and
176
+ EMPLOYEES_API name it.
177
+
146
178
  ### Regions on a REST data source
147
179
 
148
180
  A region's **REST data source** property (page designer → Source) makes it read the source's
@@ -262,6 +294,9 @@ A catalog comes from:
262
294
  - a **catalog file** downloaded from another workspace or installation (*Download* on the catalog's page);
263
295
  - **by hand**: a name and base URL, then *Add a service*.
264
296
 
297
+ A catalog may name a **remote server** of the workspace (the catalog's page, *Remote server*; sprint 141): its services
298
+ are then paths after the server's URL, and the base URL is optional.
299
+
265
300
  Reading an OpenAPI document, pgkiln takes for each `GET`, `POST`, `PUT`, `PATCH` and `DELETE` operation:
266
301
 
267
302
  | From the document | Becomes |
@@ -279,7 +314,8 @@ YAML documents: convert them to JSON first (most services offer `openapi.json` t
279
314
 
280
315
  **Making a data source from a catalog**: an application's Shared Components → REST data sources → + Add shows *From a
281
316
  REST source catalog* when the application's workspace has catalogs: pick a service, optionally another name and one
282
- of the application's web credentials. The data source is a **copy** (URL = base URL + path): changing or deleting the
317
+ of the web credentials (the application's or the workspace's). The data source is a **copy** (URL = base URL + path; on a
318
+ catalog with a **remote server**, sprint 141: the server and the path, so the source moves with the server): changing or deleting the
283
319
  catalog later doesn't change it, and *Replace from a document* on a catalog's page replaces only the catalog's
284
320
  services. Credentials never belong to a catalog: each application signs in with its own web credential.
285
321
 
@@ -320,6 +356,110 @@ A workflow calls a web service with an **`invoke_api` step** instead: the same k
320
356
  `variables`, `status_variable` and `response_variable` for the items, `&VAR.` for workflow
321
357
  variables and an optional `timeout` ([chapter 6](06-processing.md#invoke-api-steps)).
322
358
 
359
+ ## JSON sources and document views
360
+
361
+ (Sprint 142; APEX: Shared Components → Data Sources → **JSON Sources**, and JSON Relational **Duality Views**.)
362
+ A `jsonb` column is a single text item to a form, and one cell to a report. A **JSON source** describes the
363
+ documents in such a column with a **data profile**, and pgkiln makes updatable views from it, so forms, reports,
364
+ interactive grids, master-detail pages, REST (AutoREST) and MCP read and write the documents' values like columns
365
+ of a table.
366
+
367
+ ### A JSON source
368
+
369
+ Shared Components → Data Sources → **JSON Sources** → *Add JSON source*:
370
+
371
+ - **Table and jsonb column**: a column of an ordinary table (`hr.emp.profile`), or the one document column of a
372
+ *table of documents* (`id`, `doc`). The table needs a primary key: the views find their row by it. The list
373
+ shows the json and jsonb columns of the tables your SQL Workshop connection may use (an isolated workspace: its
374
+ own schemas).
375
+ - **View**: the name of the view, made in the table's schema.
376
+ - **The view also adds and deletes rows of the table**: for a table of documents. Off (the default), the view
377
+ only changes the documents of existing rows; an insert or delete through it is refused.
378
+ - **Propose from the data** reads up to 200 documents and proposes the profile: a **column** per path to a value
379
+ (nested objects become `office_city` for `office.city`), typed from the values it found (`integer`, `numeric`,
380
+ `boolean`, `date`, `timestamptz` for ISO date-times, `text`, `jsonb` for mixed or nested values), and an **array**
381
+ per list in the documents: a list of objects gets a column per key, a list of values (`["en", "nl"]`) one column
382
+ for the value itself (an empty path). Names, paths and types stay editable; columns you already named are kept.
383
+ A column can be **read only**.
384
+
385
+ **Create views** (the source's page) makes them in one transaction with your SQL Workshop connection and records
386
+ the statements in the [Change Log](03-builder.md#change-log); *Open in the SQL Worksheet* shows them first. After
387
+ changing the profile, *Make the views again* drops and makes them (a view other objects depend on can't be
388
+ dropped: the error says which). The views are ordinary database objects of your application, like the table:
389
+ put the statements in your own migration scripts for the other environments (the source itself travels with the
390
+ application's export as `json_sources`).
391
+
392
+ For `hr.emp.profile` with `{"title": "Analyst", "since": "1987-04-19", "office": {"city": "Dallas"},
393
+ "skills": [{"name": "SQL", "level": 5}], "badge": {"color": "blue"}}` the HR example's source EMP_PROFILE makes:
394
+
395
+ | View | Columns | One row per |
396
+ | --- | --- | --- |
397
+ | `hr.emp_profile` | `empno`, `title`, `since` (date), `office_city`, `office_floor` (integer), `remote` (boolean) | employee |
398
+ | `hr.emp_profile_skills` | `empno`, `row_key`, `position`, `skill`, `level` (integer) | element of `skills` |
399
+ | `hr.emp_profile_languages` | `empno`, `row_key`, `position`, `language` | element of `languages` |
400
+
401
+ - A value that doesn't read as its column's type (`"floor": "ground"`) shows **NULL** in that column instead of
402
+ failing the whole query (`meta.input_ok`, PostgreSQL's `pg_input_is_valid`).
403
+ - **Writing keeps what the profile doesn't know.** An `UPDATE` of the view writes only the paths whose values
404
+ changed, into the row's document, in one `UPDATE` of the table (`meta.jsonb_patch`): `badge` above, or any key a
405
+ newer version of another program added, stays. Setting a column to NULL removes its key; a path to a nested
406
+ object makes the objects on the way. The key columns are never changed through the view.
407
+ - **Arrays as rows.** An array view has the table's key, `row_key` and `position` (1, 2 …) and the element's
408
+ columns. `row_key` is the element's contents (an md5) and its occurrence among equal elements: it stays the same
409
+ when other elements are added, changed or removed, so deleting two rows of a grid in one save removes the right
410
+ two. An `INSERT` appends an element (the table's key column says to which row), an `UPDATE` patches one
411
+ (unknown keys of the element stay), a `DELETE` removes it. An element that someone changed meanwhile is no
412
+ longer found and the statement fails (*Reload and try again*): nothing is overwritten.
413
+ - **Security.** The views are `security_invoker` and get the table's grants (SELECT, INSERT, UPDATE, DELETE of each
414
+ role that has them on the table). Their INSTEAD OF triggers (`meta.json_source_write`, `meta.json_array_write`)
415
+ are SECURITY INVOKER too: they write the table as the role that writes the view, so its grants and the table's
416
+ row level security apply, exactly as for a direct `UPDATE`.
417
+
418
+ ### Pages on a JSON source
419
+
420
+ The views work everywhere a table does: Create Page, a form's or report's source, the interactive grid, AutoREST
421
+ and MCP. **Create page** on the source's page makes a form on the view with a **detail grid per array** (the
422
+ grid's master is the form's key item, `position` read only, `row_key` hidden) and their save processes; open it
423
+ with the key in the URL, for example from a report's link. HR page 51 *Employee profiles* (Administration) is
424
+ such a page with a report on top:
425
+
426
+ ```sql
427
+ -- the report's source: hr.emp with its jsonb column
428
+ select empno, ename, job, profile from hr.emp order by profile is null, ename
429
+ ```
430
+
431
+ ### JSON path columns in reports
432
+
433
+ A report region's **JSON path columns** (Page Designer → the report's settings) add columns read from a json or
434
+ jsonb column of its query, without writing the SQL: `name=column:path[:type]`, separated by `;`:
435
+
436
+ ```
437
+ title=profile:title; first_skill=profile:skills.0.name; since=profile:since:date
438
+ ```
439
+
440
+ A path is keys separated by dots; a number picks an element of an array (`skills.0.name`). They are columns like
441
+ the others: search, filters, sorting, control breaks, aggregates, headings, format masks and downloads. In the
442
+ region's JSON: `"json_columns": [{"name": "title", "column": "profile", "path": "title", "type": "text"}]`.
443
+
444
+ ### Document views (duality views)
445
+
446
+ SQL Workshop › Table Properties → **Document view…** (or a table's ⋯ menu) makes a view with the table's key and a
447
+ `jsonb` document per row: the row's columns and, per **child table** you tick (tables whose foreign keys reference
448
+ it), a list of its rows without the foreign key columns:
449
+
450
+ ```json
451
+ {"deptno": 10, "dname": "ACCOUNTING", "loc": "NEW YORK",
452
+ "emp": [{"empno": 7782, "ename": "CLARK", "job": "MANAGER", "sal": 2450}, …]}
453
+ ```
454
+
455
+ Writing the document back (`update hr.dept_doc set doc = $1 where deptno = 10`, or a PUT through AutoREST on the
456
+ view) updates the row's columns the document names, **upserts** the children it lists (by their key; one without
457
+ a key is inserted) and **deletes** the children it leaves out. A document without the list leaves the children
458
+ alone. An `INSERT` of a document inserts the row and its children, a `DELETE` removes the children and the row.
459
+ Full-text and vector columns are left out of the documents. Like APEX's duality views this gives REST clients and
460
+ MCP tools one document per business object; the trigger (`meta.json_document_write`) is SECURITY INVOKER, so the
461
+ tables' grants and row level security apply to every row it touches.
462
+
323
463
  ## Export, import and application files
324
464
 
325
465
  The export ([chapter 3](03-builder.md#export-format)) has two new sections: `web_credentials`
@@ -328,6 +468,8 @@ synchronisation settings, without the synchronisation's next and last run; an im
328
468
  the schedule off). In the directory format they are
329
469
  `shared/web-credentials/` and `shared/rest-sources/` ([chapter 18](18-cli.md)). Regions, lists of
330
470
  values, processes and workflow steps refer to sources and credentials by name, so nothing needs remapping.
471
+ JSON sources are part of the application (`json_sources`, in `app.yaml` of the directory format); their
472
+ views are not: they belong to your schema's migration scripts, like the table.
331
473
 
332
474
  ## Security notes
333
475
 
@@ -335,6 +477,9 @@ values, processes and workflow steps refer to sources and credentials by name, s
335
477
  internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
336
478
  - A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
337
479
  applications (it can't widen it).
480
+ - A [remote server](#remote-servers)'s URL is checked like any other URL; its environment variable can only be a
481
+ `PGKILN_SERVER_…` name, so no other part of the server's environment becomes a URL. Only the workspace's
482
+ administrators change its servers and credentials.
338
483
  - Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
339
484
  exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
340
485
  only ever sent to its own service.
@@ -0,0 +1,48 @@
1
+ -- =====================================================================
2
+ -- HR example, part 76: a remote server and a static workspace file
3
+ -- (sprint 141, AP-7; migration 141; docs/guide/19-rest-data-sources.md
4
+ -- "Remote servers", docs/guide/16-files.md "Static workspace files")
5
+ --
6
+ -- Remote server CRM (Workspace utilities → Remote servers) stands for the
7
+ -- web service of part 23: the HR example's own REST API on
8
+ -- http://127.0.0.1:3100. The REST data sources DEPARTMENTS, DEPARTMENT and
9
+ -- EMPLOYEES_API now name the server and keep only their path
10
+ -- (/a/hr/rest/v1/departments, ...). Moving the API to another host changes
11
+ -- one value: the server's base URL, e.g. https://crm.example.com, or the
12
+ -- server's environment variable PGKILN_SERVER_CRM, which wins when it is
13
+ -- set (one value per environment: development, test, production). Every
14
+ -- source on the server follows at once; the new host must still be on the
15
+ -- allow-list (PGKILN_REST_ALLOWED_HOSTS) and the workspace's network
16
+ -- access list.
17
+ --
18
+ -- brand.css is a static workspace file: every application of the
19
+ -- workspace may load it. HR loads it on every page as
20
+ -- #WORKSPACE_FILES#brand.css (Shared Components → Static application
21
+ -- files → Every page loads); another application of the workspace adds the
22
+ -- same line to share the styles.
23
+ -- =====================================================================
24
+
25
+ insert into meta.remote_server (workspace_id, static_id, name, description, base_url, env_var)
26
+ select meta.app_workspace(a.id), 'CRM', 'HR API (CRM)',
27
+ 'The HR example''s REST API, served by this pgkiln server. Set PGKILN_SERVER_CRM on another environment.',
28
+ 'http://127.0.0.1:3100', 'PGKILN_SERVER_CRM'
29
+ from meta.app a where a.alias = 'hr'
30
+ on conflict (workspace_id, static_id) do nothing;
31
+
32
+ update meta.rest_source s
33
+ set server = 'CRM', url = substr(s.url, length('http://127.0.0.1:3100') + 1)
34
+ from meta.app a
35
+ where a.id = s.app_id and a.alias = 'hr' and s.server is null
36
+ and s.name in ('DEPARTMENTS', 'DEPARTMENT', 'EMPLOYEES_API') and s.url like 'http://127.0.0.1:3100/%';
37
+
38
+ insert into meta.workspace_file (workspace_id, name, mime, content)
39
+ select meta.app_workspace(a.id), 'brand.css', 'text/css', convert_to($css$/* A static workspace file (Workspace utilities → Static workspace files):
40
+ the applications of the workspace load it as #WORKSPACE_FILES#brand.css. */
41
+ .region-header h2 { letter-spacing: .01em; }
42
+ .ws-brand { color: var(--accent, #2b62c4); font-weight: 600; }
43
+ $css$, 'utf8')
44
+ from meta.app a where a.alias = 'hr'
45
+ on conflict (workspace_id, name) do nothing;
46
+
47
+ update meta.app set static_includes = static_includes || '{#WORKSPACE_FILES#brand.css}'
48
+ where alias = 'hr' and not ('#WORKSPACE_FILES#brand.css' = any (static_includes));
@@ -0,0 +1,174 @@
1
+ -- =====================================================================
2
+ -- HR example, part 77: a JSON source (sprint 142, AP-8; migration 142;
3
+ -- docs/guide/19-rest-data-sources.md "JSON sources")
4
+ --
5
+ -- hr.emp gets a jsonb column "profile": a document per employee with a
6
+ -- job title, a start date, an office, skills (objects) and languages
7
+ -- (values), and keys no form knows about (e.g. "badge"). JSON source
8
+ -- EMP_PROFILE (Shared Components → JSON sources) describes it, and the
9
+ -- three views below are what its "Create views" makes:
10
+ --
11
+ -- hr.emp_profile empno and a column per path (title, since,
12
+ -- office_city, office_floor, remote);
13
+ -- hr.emp_profile_skills a row per skill: empno, row_key, position,
14
+ -- skill, level;
15
+ -- hr.emp_profile_languages a row per language.
16
+ --
17
+ -- Saving the form changes only the paths whose values changed, so "badge"
18
+ -- and anything else in the document stay. Page 51 "Employee profiles"
19
+ -- (Administration): a report of the employees with JSON path columns
20
+ -- (title and first skill read from the document), a form on
21
+ -- hr.emp_profile and the skills and languages as detail grids.
22
+ -- =====================================================================
23
+
24
+ alter table hr.emp add column if not exists profile jsonb
25
+ check (profile is null or jsonb_typeof(profile) = 'object');
26
+ comment on column hr.emp.profile is 'Profile document (JSON source EMP_PROFILE): title, since, office {city, floor}, remote, skills [{name, level}], languages []';
27
+
28
+ update hr.emp e set profile = p.doc::jsonb
29
+ from (values
30
+ (7839, '{"title": "Chief executive", "since": "1981-11-17", "office": {"city": "New York", "floor": 30}, "remote": false,
31
+ "skills": [{"name": "Strategy", "level": 5}, {"name": "Negotiation", "level": 4}], "languages": ["en", "fr"],
32
+ "badge": {"color": "gold", "printed": "2024-01-08"}}'),
33
+ (7698, '{"title": "Sales manager", "since": "1981-05-01", "office": {"city": "Chicago", "floor": 12}, "remote": false,
34
+ "skills": [{"name": "Sales", "level": 5}, {"name": "Coaching", "level": 3, "certified": true}], "languages": ["en", "es"]}'),
35
+ (7782, '{"title": "Accounting manager", "since": "1981-06-09", "office": {"city": "New York", "floor": 28},
36
+ "skills": [{"name": "Accounting", "level": 5}, {"name": "SQL", "level": 3}], "languages": ["en"]}'),
37
+ (7566, '{"title": "Research manager", "since": "1981-04-02", "office": {"city": "Dallas", "floor": 4}, "remote": true,
38
+ "skills": [{"name": "PostgreSQL", "level": 5}, {"name": "Statistics", "level": 4}], "languages": ["en", "de", "nl"],
39
+ "badge": {"color": "blue"}}'),
40
+ (7788, '{"title": "Analyst", "since": "1987-04-19", "office": {"city": "Dallas"}, "remote": true,
41
+ "skills": [{"name": "SQL", "level": 5}, {"name": "TypeScript", "level": 3}], "languages": ["en"]}')
42
+ ) as p (empno, doc)
43
+ where e.empno = p.empno and e.profile is null;
44
+
45
+ -- the JSON source (the builder writes this list; it travels with the application's export)
46
+ update meta.app set json_sources = json_sources || $j$[{"name": "EMP_PROFILE",
47
+ "description": "The employee profile (hr.emp.profile): job title, office, skills and languages",
48
+ "schema": "hr", "table": "emp", "key": ["empno"], "column": "profile", "view": "emp_profile",
49
+ "columns": [{"name": "title", "path": ["title"], "type": "text"}, {"name": "since", "path": ["since"], "type": "date"},
50
+ {"name": "office_city", "path": ["office", "city"], "type": "text"},
51
+ {"name": "office_floor", "path": ["office", "floor"], "type": "integer"},
52
+ {"name": "remote", "path": ["remote"], "type": "boolean"}],
53
+ "arrays": [{"name": "skills", "path": ["skills"], "view": "emp_profile_skills",
54
+ "columns": [{"name": "skill", "path": ["name"], "type": "text"}, {"name": "level", "path": ["level"], "type": "integer"}]},
55
+ {"name": "languages", "path": ["languages"], "view": "emp_profile_languages",
56
+ "columns": [{"name": "language", "path": [], "type": "text"}]}]}]$j$::jsonb
57
+ where alias = 'hr' and not json_sources @> '[{"name": "EMP_PROFILE"}]';
58
+
59
+ -- the views, as Shared Components → JSON sources → Create views makes them
60
+ create view hr.emp_profile with (security_invoker = true) as
61
+ select t.empno,
62
+ t.profile #>> array['title'] as title,
63
+ case when meta.input_ok(t.profile #>> array['since'], 'date') then (t.profile #>> array['since'])::date end as since,
64
+ t.profile #>> array['office', 'city'] as office_city,
65
+ case when meta.input_ok(t.profile #>> array['office', 'floor'], 'integer') then (t.profile #>> array['office', 'floor'])::integer end as office_floor,
66
+ case when meta.input_ok(t.profile #>> array['remote'], 'boolean') then (t.profile #>> array['remote'])::boolean end as remote
67
+ from hr.emp t;
68
+
69
+ comment on view hr.emp_profile is 'JSON source EMP_PROFILE of application hr: hr.emp.profile (made by pgkiln; Shared Components → JSON sources makes it again)';
70
+
71
+ create trigger json_source_write
72
+ instead of insert or update or delete on hr.emp_profile
73
+ for each row execute function meta.json_source_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","rows":false,"columns":[{"name":"title","path":["title"]},{"name":"since","path":["since"]},{"name":"office_city","path":["office","city"]},{"name":"office_floor","path":["office","floor"]},{"name":"remote","path":["remote"]}]}');
74
+
75
+ grant delete, insert, select, update on hr.emp_profile to "hr_app";
76
+
77
+ create view hr.emp_profile_skills with (security_invoker = true) as
78
+ select t.empno,
79
+ k.key as row_key,
80
+ k.idx + 1 as position,
81
+ e.v #>> array['name'] as skill,
82
+ case when meta.input_ok(e.v #>> array['level'], 'integer') then (e.v #>> array['level'])::integer end as level
83
+ from hr.emp t
84
+ cross join lateral meta.jsonb_element_keys(t.profile #> array['skills']) k
85
+ cross join lateral (select (t.profile #> array['skills']) -> k.idx as v) e;
86
+
87
+ comment on view hr.emp_profile_skills is 'JSON source EMP_PROFILE of application hr: the array skills of hr.emp.profile, one row per element (made by pgkiln)';
88
+
89
+ create trigger json_source_write
90
+ instead of insert or update or delete on hr.emp_profile_skills
91
+ for each row execute function meta.json_array_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","array":["skills"],"row_key":"row_key","position":"position","columns":[{"name":"skill","path":["name"]},{"name":"level","path":["level"]}]}');
92
+
93
+ grant delete, insert, select, update on hr.emp_profile_skills to "hr_app";
94
+
95
+ create view hr.emp_profile_languages with (security_invoker = true) as
96
+ select t.empno,
97
+ k.key as row_key,
98
+ k.idx + 1 as position,
99
+ e.v #>> array[]::text[] as language
100
+ from hr.emp t
101
+ cross join lateral meta.jsonb_element_keys(t.profile #> array['languages']) k
102
+ cross join lateral (select (t.profile #> array['languages']) -> k.idx as v) e;
103
+
104
+ comment on view hr.emp_profile_languages is 'JSON source EMP_PROFILE of application hr: the array languages of hr.emp.profile, one row per element (made by pgkiln)';
105
+
106
+ create trigger json_source_write
107
+ instead of insert or update or delete on hr.emp_profile_languages
108
+ for each row execute function meta.json_array_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","array":["languages"],"row_key":"row_key","position":"position","columns":[{"name":"language","path":[]}]}');
109
+
110
+ grant delete, insert, select, update on hr.emp_profile_languages to "hr_app";
111
+
112
+ -- ---------------------------------------------------------------- page 51
113
+
114
+ insert into meta.page (app_id, page_no, name, title, parent_page)
115
+ select id, 51, 'Employee profiles', 'Employee profiles', 1 from meta.app where alias = 'hr';
116
+
117
+ insert into meta.region (page_id, seq, title, type, columns, source, table_name, pk_column, pk_item, condition, config)
118
+ select p.id, r.seq, r.title, r.type, r.cols, r.source, r.table_name, r.pk_column, r.pk_item, r.condition, r.config::jsonb
119
+ from meta.page p join meta.app a on a.id = p.app_id, (values
120
+ (10, 'Employees', 'report', 12,
121
+ 'select empno, ename, job, profile from hr.emp order by profile is null, ename', null, null, null, null,
122
+ '{"hidden": ["profile"], "headings": {"empno": "No.", "ename": "Name", "job": "Job", "title": "Title (profile)", "first_skill": "First skill", "since": "Since"},
123
+ "json_columns": [{"name": "title", "column": "profile", "path": "title", "type": "text"},
124
+ {"name": "first_skill", "column": "profile", "path": "skills.0.name", "type": "text"},
125
+ {"name": "since", "column": "profile", "path": "since", "type": "date"}],
126
+ "link": {"page": 51, "column": "empno", "items": {"P51_EMPNO": "#empno#"}}, "page_size": 5}'),
127
+ (20, 'Profile', 'form', 12, null, 'hr.emp_profile', 'empno', 'P51_EMPNO', ':P51_EMPNO is not null', '{}'),
128
+ (30, 'Skills', 'grid', 8,
129
+ 'select empno, row_key, position, skill, level
130
+ from hr.emp_profile_skills
131
+ where empno::text = :P51_EMPNO
132
+ order by position', 'hr.emp_profile_skills', 'row_key', null, ':P51_EMPNO is not null',
133
+ '{"master": {"item": "P51_EMPNO", "column": "empno"}, "readonly": ["position"], "layout": {"hidden": ["empno", "row_key"]},
134
+ "headings": {"position": "#", "skill": "Skill", "level": "Level (1-5)"}, "columns": {"skill": {"required": true}}, "row_actions": {"delete": true}}'),
135
+ (40, 'Languages', 'grid', 4,
136
+ 'select empno, row_key, position, language
137
+ from hr.emp_profile_languages
138
+ where empno::text = :P51_EMPNO
139
+ order by position', 'hr.emp_profile_languages', 'row_key', null, ':P51_EMPNO is not null',
140
+ '{"master": {"item": "P51_EMPNO", "column": "empno"}, "readonly": ["position"], "layout": {"hidden": ["empno", "row_key"]},
141
+ "headings": {"position": "#", "language": "Language"}, "row_actions": {"delete": true}}')
142
+ ) as r (seq, title, type, cols, source, table_name, pk_column, pk_item, condition, config)
143
+ where a.alias = 'hr' and p.page_no = 51;
144
+
145
+ insert into meta.item (page_id, region_id, seq, name, label, type, source_column)
146
+ select p.id, r.id, i.seq, i.name, i.label, i.type, i.col
147
+ from meta.page p join meta.app a on a.id = p.app_id
148
+ join meta.region r on r.page_id = p.id and r.title = 'Profile', (values
149
+ (10, 'P51_EMPNO', 'Employee', 'hidden', 'empno'),
150
+ (20, 'P51_TITLE', 'Title', 'text', 'title'),
151
+ (30, 'P51_SINCE', 'Since', 'date', 'since'),
152
+ (40, 'P51_OFFICE_CITY', 'Office city', 'text', 'office_city'),
153
+ (50, 'P51_OFFICE_FLOOR', 'Office floor', 'number', 'office_floor'),
154
+ (60, 'P51_REMOTE', 'Works remotely', 'switch', 'remote')
155
+ ) as i (seq, name, label, type, col)
156
+ where a.alias = 'hr' and p.page_no = 51;
157
+
158
+ insert into meta.button (page_id, region_id, seq, name, label, action, hot)
159
+ select p.id, r.id, 10, 'SAVE', 'Apply Changes', 'submit', true
160
+ from meta.page p join meta.app a on a.id = p.app_id
161
+ join meta.region r on r.page_id = p.id and r.title = 'Profile'
162
+ where a.alias = 'hr' and p.page_no = 51;
163
+
164
+ insert into meta.process (page_id, region_id, seq, name, type, point)
165
+ select p.id, r.id, r.seq, case r.type when 'form' then 'Process form Profile' else 'Save ' || r.title end,
166
+ case r.type when 'form' then 'form_dml' else 'grid_dml' end, 'submit'
167
+ from meta.page p join meta.app a on a.id = p.app_id
168
+ join meta.region r on r.page_id = p.id and r.type in ('form', 'grid')
169
+ where a.alias = 'hr' and p.page_no = 51;
170
+
171
+ insert into meta.nav_entry (app_id, parent_id, seq, label, icon, target_page)
172
+ select a.id, n.id, 80, 'Employee profiles', 'id-card', 51
173
+ from meta.app a join meta.nav_entry n on n.app_id = a.id and n.label = 'Administration' and n.parent_id is null
174
+ where a.alias = 'hr';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pgkiln",
3
- "version": "0.73.0",
3
+ "version": "0.75.0",
4
4
  "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
5
5
  "keywords": [
6
6
  "postgresql",
package/src/ai/service.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { owner } from '../db.ts';
2
2
  import { decryptSecret } from '../secrets.ts';
3
+ import { aiServerUrl } from '../remote-servers.ts';
3
4
  import { ClaudeProvider } from './anthropic.ts';
4
5
  import { OpenAiProvider } from './openai.ts';
5
6
  import { AiError, type AiProvider, type GenerateRequest, type GenerateResult, type ProviderName } from './types.ts';
@@ -27,6 +28,9 @@ export interface AiService {
27
28
  base_url: string | null;
28
29
  api_key_enc: string | null;
29
30
  enabled: boolean;
31
+ /** (141) a remote server whose base URL (plus server_path) the service calls instead of base_url */
32
+ server_id?: number | null;
33
+ server_path?: string | null;
30
34
  }
31
35
 
32
36
  /** The default model of a new Claude service; OpenAI services name theirs. */
@@ -78,7 +82,12 @@ export function serviceKey(s: AiService): string {
78
82
  }
79
83
 
80
84
  export async function loadService(name: string): Promise<AiService | undefined> {
81
- return owner.one<AiService>('select * from meta.ai_service where name = $1', [name.toUpperCase()]);
85
+ const s = await owner.one<AiService>('select * from meta.ai_service where name = $1', [name.toUpperCase()]);
86
+ if (!s?.server_id) return s;
87
+ // (141) on a remote server: its URL now (base_url is then what baseUrlFor gives the SDK)
88
+ const r = await aiServerUrl(s.server_id, s.server_path);
89
+ if (!r.url) throw new AiError('config', `AI service ${s.name}: ${r.problem}`);
90
+ return { ...s, base_url: r.url };
82
91
  }
83
92
 
84
93
  /** The provider of a service, with its key (decrypted only here, never stored elsewhere). */
package/src/app.ts CHANGED
@@ -27,6 +27,8 @@ import { ldapRoutes } from './builder/ldap.ts';
27
27
  import { aiRoutes } from './builder/ai.ts';
28
28
  import { aiAgentRoutes } from './builder/ai-agents.ts';
29
29
  import { vectorProviderRoutes } from './builder/vector-providers.ts';
30
+ import { jsonSourceRoutes } from './builder/json-sources.ts';
31
+ import { documentViewRoutes } from './builder/document-view.ts';
30
32
  import { mailRoutes } from './builder/mail.ts';
31
33
  import { backupRoutes } from './builder/backups.ts';
32
34
  import { availabilityRoutes } from './builder/availability.ts';
@@ -96,6 +98,7 @@ import { findWorkspaceRoutes } from './builder/find-workspace.ts';
96
98
  import { mailQueueRoutes } from './builder/mail-queue.ts';
97
99
  import { networkAccessRoutes } from './builder/network-access.ts';
98
100
  import { workspaceMailRoutes } from './builder/workspace-mail.ts';
101
+ import { workspaceResourceRoutes } from './builder/workspace-resources.ts';
99
102
  import { runtimeScope } from './db.ts';
100
103
  // (sprint 139, AP-6) OpenTelemetry: a trace per request, /metrics, the browser relay
101
104
  import { startTelemetry } from './telemetry/export.ts';
@@ -251,6 +254,9 @@ export async function buildApp(opts: { logger?: boolean } = {}) {
251
254
  await app.register(aiAgentRoutes);
252
255
  // (sprint 136, AP-1) vector providers: Shared Components and Workspace utilities
253
256
  await app.register(vectorProviderRoutes);
257
+ // (sprint 142, AP-8) JSON sources (Shared Components) and document views (Table Properties)
258
+ await app.register(jsonSourceRoutes);
259
+ await app.register(documentViewRoutes);
254
260
  await app.register(mailRoutes);
255
261
  await app.register(backupRoutes);
256
262
  await app.register(availabilityRoutes);
@@ -281,6 +287,7 @@ export async function buildApp(opts: { logger?: boolean } = {}) {
281
287
  await app.register(mailQueueRoutes);
282
288
  await app.register(networkAccessRoutes);
283
289
  await app.register(workspaceMailRoutes);
290
+ await app.register(workspaceResourceRoutes);
284
291
  // (sprint 138, AP-5) an application's Utilities
285
292
  await app.register(utilityRoutes);
286
293
  await app.register(dependencyRoutes);
@@ -387,6 +387,10 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
387
387
  // (104) a document button names a document template or a report query
388
388
  const documents = new Set(all.filter((x) => x.kind === 'document_template' || x.kind === 'report_query').map((x) => x.row.name.toUpperCase()));
389
389
  const missing = (entry: Entry | null, field: string, message: string, severity: Severity = 'error') => findings.push({ severity, entry, field, message });
390
+ // (141) remote servers and web credentials of the application's workspace (sources and invoke steps may name them)
391
+ const wsServers = new Map((await query('select static_id, credential from meta.remote_server where workspace_id = meta.app_workspace($1)', [appId])).rows.map((r) => [r.static_id as string, r.credential as string | null]));
392
+ const wsCredentials = new Set((await query('select name from meta.workspace_credential where workspace_id = meta.app_workspace($1)', [appId])).rows.map((r) => r.name as string));
393
+ const appCredentials = new Set(all.filter((x) => x.kind === 'web_credential').map((x) => String(x.row.name).toUpperCase()));
390
394
 
391
395
  for (const e of entries) {
392
396
  for (const f of e.fields) {
@@ -457,6 +461,14 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
457
461
  if (kind === 'button' && row.action === 'document' && !documents.has(String(row.document ?? '').toUpperCase()))
458
462
  missing(e, 'Document template', row.document ? `Document template or report query ${row.document} doesn't exist.` : 'A document button needs a document template or a report query.');
459
463
  if (kind === 'rest_module') for (const problem of handlerProblems(row.handlers)) missing(e, 'Handlers (JSON)', problem);
464
+ if (kind === 'rest_source') {
465
+ // (141) an export may name a server or credential this workspace doesn't have (yet): it imports, and says so here
466
+ if (row.server && !wsServers.has(row.server))
467
+ missing(e, 'Remote server', `Remote server ${row.server} doesn't exist in this application's workspace: add it under Workspace utilities → Remote servers (calls fail until then).`, 'warning');
468
+ const credential = row.credential || (row.server ? wsServers.get(row.server) : null);
469
+ if (credential && !appCredentials.has(credential) && !wsCredentials.has(credential))
470
+ missing(e, 'Web credential', `Web credential ${credential} is neither the application's nor its workspace's (calls fail until it exists).`, 'warning');
471
+ }
460
472
  if (kind === 'workflow_definition') {
461
473
  const tasks = new Set(all.filter((x) => x.kind === 'task_definition').map((x) => x.row.name.toUpperCase()));
462
474
  const outcomes = outcomeMap(all.filter((x) => x.kind === 'task_definition').map((x) => x.row));
@@ -465,7 +477,7 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
465
477
  // invoke_api steps: REST data sources, parameters, web credentials, variables (sprint 32)
466
478
  const refs = {
467
479
  sources: new Map(all.filter((x) => x.kind === 'rest_source').map((x) => [String(x.row.name).toUpperCase(), x.row])),
468
- credentials: new Set(all.filter((x) => x.kind === 'web_credential').map((x) => String(x.row.name).toUpperCase())),
480
+ credentials: new Set([...appCredentials, ...wsCredentials]),
469
481
  startVars: [...String(row.title ?? '').matchAll(/&([A-Za-z][A-Za-z0-9_]*)\./g)].map((m) => m[1]),
470
482
  };
471
483
  const invokeRefs = invokeStepReferences(row.steps, refs);