@bananacool467/authtics-host 0.2.5 → 0.2.7

package/.agents/memory/MEMORY.md

@@ -0,0 +1 @@
+- [Node child-process test cleanup](node-child-process-tests.md) — a signaled child can have `exitCode === null`; check `signalCode` too.

package/.agents/memory/node-child-process-tests.md

@@ -0,0 +1,10 @@
+---
+name: Node child-process test cleanup
+description: Avoid hanging integration-test cleanup when a fixture server exits from a signal.
+---
+
+When a Node child process is terminated by a signal, `exitCode` remains `null` and `signalCode` identifies how it exited. Treat either a non-null exit code or signal code as completion.
+
+**Why:** Fixture-server tests can otherwise wait for an `exit` event that already fired and be cancelled when the event loop empties.
+
+**How to apply:** In child-process test helpers, check both `exitCode` and `signalCode`, and register the exit listener before sending a termination signal.

package/README.md

@@ -1,17 +1,11 @@
 # Authtics Host
 
-Version 0.2.5, License: MIT
+Version 0.2.7, License: MIT
 
-Authtics Host is a web framework inspired by Next.js. Authtics Host supports SSR (Server-Side Rendering) and uses esbuild. This is not to be confused with auth platforms.
+Authtics Host is a web framework inspired by Next.js. Authtics Host supports SSR (Server-Side Rendering), SSG (Static Site Generation), CSR (Client-Side Rendering) and SRTWS (Site Rendering Through WebSockets) and uses **Esbuild**. This is not to be confused with auth platforms.
 
 **(NOTE: The short name for Authtics Host is HostJS or Host.js)**
 
-**(From the Developer: I am having 1 small issue:**
-
-1. **Web Socket Connections** are **not showing** in the DevPanel's Network tab
-
-**I need help fixing that)**
-
 ## Setting Up
 
 To get **Authtics Host** use:
@@ -51,7 +45,7 @@ import { defineConfig } from "@bananacool467/authtics-host";
 
 export default defineConfig({
   port: 8000,
-  ssr: true,
+  renderType: 'ssr',
   devMode: true,
   autoFile: true,
   autoPage: true,
@@ -94,7 +88,7 @@ import { defineConfig } from "@bananacool467/authtics-host";
 
 export default defineConfig({
   port: 8000,
-  ssr: true,
+  renderType: 'ssr',
   devMode: true,
   autoFile: false,
   autoPage: false
@@ -131,6 +125,36 @@ export default function Index () {
 }
 ```
 
+## Build Output Styles
+
+HostJS supports two output layouts through `buildStyle` in `authtics_host.config.ts`.
+
+- `default` (the default) keeps the existing `.authtics_host/` cache layout.
+- `super` enables the Next.js-inspired `.hostjs/` layout with separated client/server bundler caches, route-cache files, route and middleware manifests, generated route type files, diagnostics metadata, and trace directories.
+
+To opt in, add this to your existing `defineConfig({ ... })` object:
+
+```ts
+buildStyle: "super"
+```
+
+The setting is opt-in, so projects that do not specify it continue using `default`.
+
+## Build Triggers
+
+HostJS supports two ways to trigger page bundle compilation using `buildTrigger` in `authtics_host.config.ts`.
+
+- `default` (the default) compiles a TSX page on demand when a request needs it.
+- `prebuilt` compiles discoverable TSX pages during Authtics Host startup, before the HTTP server begins listening. SSR pages are compiled without eagerly invoking their page components; SSG pages are rendered during startup so their static HTML is ready. Startup reports a prebuild error instead of opening the server if compilation (or SSG generation) fails.
+
+Prebuilt mode scans the configured auto-page directory for TSX pages and also prebuilds a registered `app.registerApp(...)` entry when it points to an existing TSX file. API handlers and static files are not TSX renderer bundles, so they are not prebuilt by this option. The renderer reuses generated caches in both `default` and `super` build styles.
+
+To opt in, add this to your existing `defineConfig({ ... })` object:
+
+```ts
+buildTrigger: "prebuilt"
+```
+
 ## To Run The Project
 
 Make sure **Node 22** is installed:
@@ -152,9 +176,13 @@ node --experimental-strip-types index.ts
 
 Then when you run your project, you will get a page just saying **"Hello, World!"** and you should see a clickable Developer Panel at the bottom-right.
 
+![Result](assets/result.jpg)
+
 ## About The Developer Panel
 
-The Developer Panel is what you could use to help you debug your code. The Developer Panel has **7 tabs**:
+![Developer Panel](assets/dev_panel.jpg)
+
+The Developer Panel is what you could use to help you debug your code. The Developer Panel has **8 tabs**:
 
 * **Console** — Shows current logs.
 * **Route** — Shows information about the current route.
@@ -163,6 +191,7 @@ The Developer Panel is what you could use to help you debug your code. The Devel
 * **Client Info** — Shows information about your client's User Agent, OS **(Operating System)** and FPS **(Frames Per Second)**.
 * **About Host** — Shows the current version of *Authtics Host*.
 * **Server Info** — Shows how much heap was used and how much CPU was used on the server and how much requests there were and how much users are currently on the site and how long the site has been up.
+* **Panel Customization** — Customize the dev panel.
 
 The information the Developer Panel shows outside of the tabs is just your **DAT** (Developer Access Token).
 
@@ -186,6 +215,48 @@ and then create a file like `paused.tsx` and then inside `App.tsx`, import `Paus
 ```
 and if your using `autoPaging` then you just create a file named `_paused.tsx`.
 
+## Page Patching
+
+Pages may fail to render in SSR if it uses `window` instead of assigning it to a **useState** while in a **useEffect** in *React*
+
+You can fix this by adding this to your config file:
+```json
+"patchForServer": true
+```
+
+It makes a fake `window`, `document`, etc for SSR when building for Node. Which fixes the issue.
+
+## Browser API
+
+You can set, delete and get cookies using Authtics Host's BrowserAPI (BAPI) feature. Example:
+
+```typescript
+import {
+  Cookies
+} from "@bananacool467/authtics-host";
+
+const cookies = new Cookies();
+// set
+cookies.set("name", "value");
+// get
+const data = cookies.get("name");
+// delete
+cookies.del("name");
+```
+
+You can also enable stuff on cookies, like:
+* **Secure**
+* **Max Age / Expires**
+* **Same Site**
+
+Example:
+```typescript
+cookies.set("name", "value", true, "Lax", 2 * 24 * 60 * 60);
+```
+* **Secure** is `true`
+* **Same Site** is `Lax`
+* **Max Age** is `2 * 24 * 60 * 60` (2 days)
+
 ## App APIs
 
 You can add APIs like `get`, `post`, `del` and `put`.
@@ -201,34 +272,72 @@ Then when you go to `/hi` you see:
 Hello!
 ```
 
-## Notes about Authtics Host
-
-Since Authtics Host is SSR, stuff like NPM packages that uses **Browser APIs** (e.g., `window`, `document`) will cause errors.
-The developer (The one that is writing this README) may add a feature where Authtics Host converts:
-```tsx
-export function Component() {
-  return (
-    <p>{window.__status_code__}</p>
-  )
-}
+You can add an `on` event onto the Node.js server by using `on(event, handler)`, example:
+```typescript
+app.on("upgrade", (req, socket, head) => {
+  if (req.headers['upgrade'] && req.headers['upgrade'].toLowerCase() === 'websocket') {
+    // any code here
+  }
+});
 ```
-To:
-```tsx
-import { useState, useEffect } from 'react';
-export function Component() {
-  const [__window, __set_window] = useState<any>(null);
-  useEffect(() => {
-    if (window) __set_window(window);
-  }, []);
-  return (
-    <p>{__window.__status_code__}</p>
-  )
-}
+
+You can also add an `use` event onto the HostJS App, when a user visits the page, the first `use` event runs on it before reaching any other route, any other `use` event doesn't run until you call `next()`. Example:
+```typescript
+app.use((req, res, id, next) => {
+  console.log("Request cookies: " + req.cookies);
+  return next();
+});
+
+app.use((req, res, id, next) => {
+  console.log("2nd USE event ran.");
+});
+
+app.use((req, res, id, next) => {
+  console.log("3rd...");
+})
 ```
 
-The developer might also redesign the UI for the DevPanel using [UI Tools](https://npmjs.com/package/@bananakitssu/ui-tools).
+The 3rd USE event will never run because the 2nd USE event didnt use `next()`.
+
+## SRTWS
+
+SRTWS is **Site Rendering Through WebSockets**, its currently in BETA.
+
+When a client visits your site if renderer is set to SRTWS, a **SRTWS server** starts and the client connects to it. Then, the **SRTWS server** sends the entire compiled TSX to the client.
+
+## REQuest APIs
+
+The `req` variable (like used in `app.get`) is an extension of the ***Node.js HTTP IncomingMessage*** class, the added items in `req` are:
+
+* **dat** (`req.dat`) — The user's DAT cookie for the current App.
+* **cookies** (`req.cookies`) — All the extracted user's cookies for the current App.
+* **body** (`req.body` for POST) — The parsed `body` that was sent from client.
+* **ip** (`req.ip`) — The request's IP.
+* **ipType** (`req.ipType`) — The IP's type as a number, 6 is IPv6, 4 is IPv4, 0 is unknown.
+* **ua** (`req.ua`) — The request's UserAgent.
+* **os** (`req.os`) — The request's OS from the UserAgent.
+* **browser** (`req.browser`) — The request's browser from the UserAgent.
+* **sentTime** (`req.sentTim.e`) — When the request was sent
+* **bodySize** (`req.bodySize` for POST) — The size of the body. (`req.body`)
+* **bodyType** (`req.bodyType`) — The Content-Type of the body. (`req.body`)
+
+## RESponse APIs
+
+The `res` variable (like used in `app.get`) is an extension of the ***Node.js HTTP ServerResponse*** class, the added items in `res` are:
+
+* **redirect** (`res.redirect(url)`) — Send the client to another URL.
+* **html** (`res.html(content)`) — Return HTML to the client.
+* **json** (`res.json(content)`) — Return JSON to the client.
+* **text** (`res.text(content)`) — Return plain text to the client.
+* **file** (`res.file(path)`) — Let HostJS read the provided file path and return the file content to the client.
+* **status** (`res.status(code)`) — Change the server's status code, returns new **ServerResponse** object.
+* **reload** (`res.reload()`) — Send a reload request to the client.
+* **setCookie** (`res.setCookie(name, value)`) — Set a cookie on the client.
+* **rmvCookie** (`res.rmvCookie(name)`) — Remove a cookie from the client.
+
+## Notes about Authtics Host
 
-And also maybe, add Developer Panel customization.
+The developer might redesign the UI for the DevPanel using [UI Tools](https://npmjs.com/package/@bananakitssu/ui-tools).
 
 > **Warning**:
 > Asking AI about HostJS is not recommended, it will give an Auth platform and call HostJS/Authtics Host a typo, say it doesn't exist, say it was renamed, it is private, or the account doesn't exist. Or if it knows, it may swap your server script with regular **Node.js**/**ExpressJS**/**Next.js** or use **Next.js-like** code because this framework is **Next.js-inspired**
@@ -263,4 +372,4 @@ I named this web framework Authtics Host because it uses DAT (For the **Auth**ti
 
 ## Contacting The Developer Of Authtics Host
 
-If you have any questions, or encountered a bug while using HostJS, contact: authtics@proton.me
+If you have any questions, or encountered a bug while using HostJS, contact: authtics@proton.me

package/dist/BrowserAPIs.d.ts

@@ -0,0 +1,10 @@
+type bAPI = 'navigator' | 'window' | 'document' | 'location' | 'localStorage' | 'sessionStorage' | 'fetch' | 'XMLHttpRequest';
+export declare function load(browserAPI: bAPI): Promise<any>;
+export declare class Cookies {
+    private Document;
+    constructor();
+    set(name: string, value: string, sameSite?: string, Secure?: boolean, MaxAge?: number | null): Promise<void>;
+    get(name: string): Promise<string | undefined>;
+    del(name: string): Promise<void>;
+}
+export {};

package/dist/BrowserAPIs.js

@@ -0,0 +1,53 @@
+'use strict';
+export async function load(browserAPI) {
+    while (typeof window === "undefined") {
+        return null;
+    }
+    const apiMap = {
+        navigator: window.navigator,
+        window: window,
+        document: window.document,
+        location: window.location,
+        localStorage: window.localStorage,
+        sessionStorage: window.sessionStorage,
+        fetch: window.fetch.bind(window),
+        XMLHttpRequest: window.XMLHttpRequest
+    };
+    return apiMap[browserAPI];
+}
+export class Cookies {
+    Document;
+    constructor() {
+        this.Document = load('document');
+    }
+    async set(name, value, sameSite = "Lax", Secure = true, MaxAge = null) {
+        const Document = this.Document;
+        const cookieParts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`, "Path=/"];
+        if (MaxAge !== null) {
+            cookieParts.push(`max-age=${MaxAge}`);
+            const d = new Date();
+            d.setTime(d.getTime() + (MaxAge * 1000));
+            cookieParts.push(`expires=${d.toUTCString()}`);
+        }
+        if (Secure)
+            cookieParts.push("secure");
+        if (sameSite)
+            cookieParts.push(`samesite=${sameSite}`);
+        Document.cookie = cookieParts.join("; ");
+    }
+    async get(name) {
+        const Document = this.Document;
+        const cookies = Document.cookie.split(";").filter(Boolean);
+        for (const c of cookies) {
+            const [key, ...valParts] = c.trim().split("=");
+            if (decodeURIComponent(key) === name) {
+                return decodeURIComponent(valParts.join("="));
+            }
+        }
+        return undefined;
+    }
+    async del(name) {
+        const Document = await load('document');
+        Document.cookie = `${encodeURIComponent(name)}=; path=/; max-age=0; samesite=Lax; secure`;
+    }
+}

package/dist/cli.d.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-import { IncomingMessage, ServerResponse } from "node:http";
+import { IncomingMessage, ServerResponse, Server } from "node:http";
 export default class App {
-    server: any;
+    server: Server | null | undefined;
     constructor();
     startServer(): Promise<void>;
-    get(routePath: string, handler: (req: IncomingMessage, res: ServerResponse) => void): void;
     registerApp(route: string): void;
+    get(routePath: string, handler: (req: IncomingMessage, res: ServerResponse) => void): void;
     post(routePath: string, handler: (req: IncomingMessage, res: ServerResponse) => void): void;
     put(routePath: string, handler: (req: IncomingMessage, res: ServerResponse) => void): void;
     delete(routePath: string, handler: (req: IncomingMessage, res: ServerResponse) => void): void;
+    use(handler: (req: IncomingMessage, res: ServerResponse, id: bigint | null, next: Function) => void): void;
+    on(method: string, handler: (...args: any[]) => void): void;
     remove(method: string, routePath: string): void;
 }