Merge branch 'next' of github.com:devforth/adminforth into next

Author: SerVitasik

adminforth/dataConnectors/postgres.ts

@@ -5,13 +5,19 @@ import AdminForthBaseConnector from './baseConnector.js';
 import pkg from 'pg';
 import { afLogger, dbLogger } from '../modules/logger.js';
 
-const { Client } = pkg;
+const { Pool } = pkg;
+const { Client, types } = pkg;
+
+// postgres-date (used by pg for OID 1114/1082) parses no-TZ strings with new Date(y,m,d,...)
+// which treats them as LOCAL server time. Return raw strings so getFieldValue can parse as UTC.
+types.setTypeParser(1114, (val) => val); // TIMESTAMP WITHOUT TIME ZONE
+types.setTypeParser(1082, (val) => val); // DATE
 
 
 class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDataSourceConnector {
 
     async setupClient(url: string): Promise<void> {
-        this.client = new Client({
+        this.client = new Pool({
             connectionString: url
         });
         try {
@@ -200,7 +206,7 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
                 return null;
             }
             if (field._underlineType == 'timestamp' || field._underlineType == 'int') {
-                return dayjs(value).toISOString();
+                return dayjs(value.replace(' ', 'T') + 'Z').toISOString();
             } else if (field._underlineType == 'varchar') {
                 return dayjs(value).toISOString();
             } else {
@@ -212,7 +218,7 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
             if (!value) {
                 return null;
             }
-            return dayjs(value).toISOString().split('T')[0];
+            return value;
         }
 
         if (field.type == AdminForthDataTypes.BOOLEAN) {

adminforth/documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -52,9 +52,9 @@ When user clicks the "Save" button on edit page, AdminForth makes a request to t
 
 ![Saving data on edit page](image-27.png)
 
-Practically you can use `edit.beforeSave` hook to modify the data or populate new fields before it is saved to the database.
+Practically you can use `hooks.edit.beforeSave` hook to modify the data or populate new fields before it is saved to the database.
 
-> 👆 Note: according to diagram you should understand that interrupting flow from `edit.afterSave` does not prevent data modification in DB
+> 👆 Note: according to diagram you should understand that interrupting flow from `hooks.edit.afterSave` does not prevent data modification in DB
 
 ## Saving data on create page
 
@@ -266,4 +266,4 @@ always performed before any hooks and any database requests.
 
 ## All hooks
 
-Check all hooks in the [API reference](/docs/api/Back/interfaces/AdminForthResource).
+Check all hooks in the [API reference](/docs/api/Back/interfaces/AdminForthResource).

adminforth/documentation/docs/tutorial/03-Customization/16-websocket.md

@@ -3,6 +3,8 @@
 
 AdminForth provide own build-in websocket interface which allows to stream some data to frontend from backend.
 
+If in production you run through a reverse proxy such as Nginx, ensure websocket upgrade is enabled on the `/afws` path under your AdminForth base URL, otherwise websocket will not work. See [Deploy in Docker > Nginx version](/docs/tutorial/deploy#nginx-version).
+
 In two words, to subscribe to a topic from any frontend component you need to do next
 
 ```javascript

adminforth/documentation/docs/tutorial/04-deploy.md

@@ -115,13 +115,18 @@ docker compose -p stack-my-app -f compose.yml up -d --build --remove-orphans --w
 If you want to deploy your AdminForth application to a sub-folder like `https://mydomain.com/admin` you
 should do the following:
 
-1) Open `index.ts` file and change `ADMIN_BASE_URL` constant to your subpath:
+1) Open `index.ts` file and set the same subpath in `ADMIN_BASE_URL` and `baseUrl`:
 
 ```ts title='./index.ts'
 //diff-remove
 const ADMIN_BASE_URL = '';
 //diff-add
 const ADMIN_BASE_URL = '/admin/';
+
+export const admin = new AdminForth({
+  baseUrl: ADMIN_BASE_URL,
+  ...
+});
 ```
 
 2) Open `compose.yml` file and change `traefik.http.routers.adminforth.rule` to your subpath:
@@ -141,11 +146,18 @@ Now you can access your AdminForth application by going to `https://mydomain.com
 
 If you want to automate the deployment process with CI follow [our docker - traefik guide](https://devforth.io/blog/onlogs-open-source-simplified-web-logs-viewer-for-dockers/)
 
-# Nginx version
+## Nginx version
 
-If you are using Nginx instead of traefik, here is siple proxy pass config:
+If you are using Nginx instead of traefik, proxy both regular HTTP traffic and AdminForth websocket endpoint.
 
-```
+AdminForth websocket always uses `<baseUrl>/afws`, where `<baseUrl>` is the same value you pass to `baseUrl: ADMIN_BASE_URL` in `index.ts`.
+
+- If `ADMIN_BASE_URL = ''`, use `/afws`.
+- If `ADMIN_BASE_URL = '/admin/'`, use `/admin/afws`.
+
+For root deployment, the config can look like this:
+
+```nginx
 server {
   listen 80;
   server_name demo.adminforth.dev;
@@ -163,6 +175,17 @@ server {
   gzip_min_length 2000;
   gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype image/svg+xml image/x-icon;
 
+  location /afws {
+    proxy_http_version 1.1;
+    proxy_read_timeout 220s;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Host $http_host;
+    proxy_redirect off;
+    proxy_pass http://127.0.0.1:3500;
+  }
+
   location / {
       proxy_read_timeout 220s;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -173,6 +196,35 @@ server {
 }
 ```
 
+If you deploy AdminForth under a subpath, use the same prefix in Nginx locations. For example, when `ADMIN_BASE_URL = '/admin/'`, the websocket path becomes `/admin/afws`:
+
+```nginx
+server {
+  ...
+
+  location /admin/afws {
+      proxy_http_version 1.1;
+      proxy_read_timeout 220s;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection "upgrade";
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header Host $http_host;
+      proxy_redirect off;
+      proxy_pass http://127.0.0.1:3500;
+  }
+
+  location /admin/ {
+      proxy_read_timeout 220s;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header Host $http_host;
+      proxy_redirect off;
+      proxy_pass http://127.0.0.1:3500;
+  }
+}
+```
+
+If websocket upgrade is not configured on the correct `<baseUrl>/afws` path, realtime AdminForth features will not work behind Nginx.
+
 # Environment variables best practices
 
 Use `.env` file for sensitive variables like `OPENAI_API_KEY` locally.