@bananacool467/authtics-host 0.2.6 → 0.2.8

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,6 +1,6 @@
 # Authtics Host
 
-Version 0.2.6, License: MIT
+Version 0.2.8, License: MIT
 
 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.
 
@@ -17,6 +17,11 @@ or
 npm install @bananacool467/authtics-host@latest
 ```
 
+You may have to get **React** and **React DOM**:
+```bash
+npm i @types/react @types/react-dom
+```
+
 You can have auto paging enabled, auto paging checks your given directory for HTML and TSX files and then adds them to route. If auto filing is enabled, auto filing will check your given directory for files and add them accessible to route.
 
 To make your app, with auto paging and auto filing, your file tree should look like:
@@ -125,6 +130,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:
@@ -142,12 +177,21 @@ To run the project use:
 node --experimental-strip-types index.ts
 ```
 
+Or:
+```
+hostjs start
+```
+
 ## Result
 
 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
 
+![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.
@@ -187,11 +231,42 @@ Pages may fail to render in SSR if it uses `window` instead of assigning it to a
 
 You can fix this by adding this to your config file:
 ```json
-"patchForSsr": true
+"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`.
@@ -207,13 +282,73 @@ Then when you go to `/hi` you see:
 Hello!
 ```
 
+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
+  }
+});
+```
+
+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 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
 
 The developer might redesign the UI for the DevPanel using [UI Tools](https://npmjs.com/package/@bananakitssu/ui-tools).
 
-> **Warning**:
-> SRTWS may not work properly. It may render pages, but not run scripts.
-
 > **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**
 
@@ -241,10 +376,37 @@ There isn't any limit of DATs you can add.
 
 **(Note: Adding your DAT will give you access to Restart and Shutdown and Pause/Resume Users and other features in the Developer Panel)**
 
+## HostJS commands
+
+There are 3 different HostJS commands:
+
+```bash
+hostjs -v
+# or:
+hostjs --version
+# or:
+hostjs version
+```
+Returns the current HostJS *version*.
+
+```bash
+hostjs help
+```
+Returns all the avaliable HostJS commands.
+
+```bash
+hostjs start
+```
+Runs `node --experimental-strip-types index.ts` but you can use:
+```bash
+hostjs start path/to/script.ts
+```
+Which runs the same command but uses the path to the script instead of `index.ts`
+
 ## Reasons for the name, Authtics Host
 
 I named this web framework Authtics Host because it uses DAT (For the **Auth**tics part) for developer authentication for dev panel, and for "Host" is because it let's the developer **Restart**/**Shutdown** the server.
 
 ## 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/bin/hostjs.js

@@ -0,0 +1,62 @@
+import { parseArgs } from 'node:util';
+import { logger } from './logger.js';
+import { spawnSync } from 'node:child_process';
+import path from "node:path";
+import fs from "node:fs/promises";
+import url from "node:url";
+
+const { positionals } = parseArgs({
+  allowPositionals: true
+});
+
+const [arg, arg2] = positionals;
+if ( !arg ) {
+  process.exit(0);
+}
+
+if ( arg != "help" && arg != "version" && arg != "--version" && arg != "start" && arg != "-v" ) {
+  logger.error(`Unknown command: \x1b[33m${arg}`);
+  logger.skip();
+  logger.notice("You can get commands by typing \"hostjs help\".");
+  process.exit(1);
+} else if ( arg == "help" ) {
+  logger.log("Avaliable HostJS commands:");
+  logger.skip();
+  logger.log("  help    => Get help with HostJS commands.");
+  logger.log("  version => See the current downloaded version.");
+  logger.log("    [-v|--version] => Other ways to get version.");
+  logger.log("  start   => Start your website.");
+} else if ( arg == "start" ) {
+  logger.notice("Starting...");
+  let file = "index.ts";
+  const command = "node";
+  const commandArg = "--experimental-strip-types";
+  if ( arg2 != null ) file = arg2;
+
+  const result = spawnSync(command, [commandArg, file], { stdio: 'inherit' });
+
+  if ( result.status !== 0 ) {
+    logger.error(`Process exited with code ${result.status}`);
+    process.exit(result.status || 1);
+  }
+} else if ( arg == "-v" || arg == "version" || arg == "--version" ) {
+  const __filename = url.fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const packageJsonPath = path.join(__dirname, '..', 'package.json');
+  async function loadPackageConfig() {
+    try {
+      const rawData = await fs.readFile(packageJsonPath, 'utf-8');
+
+      const packageJson = JSON.parse(rawData);
+
+      return packageJson
+    } catch (error) {
+      logger.error('Failed to read package.json:', error);
+      process.exit(1);
+    }
+  }
+
+  const package_ = await loadPackageConfig();
+  logger.notice(`Authtics Host version: ${package_.version}`);
+}
+process.exit(0);

package/bin/logger.js

@@ -0,0 +1,29 @@
+function skip () {
+  return console.log('');
+}
+
+function error (msg) {
+  return console.error(`[HostJS \x1b[31mError\x1b[0m]: \x1b[31m${msg}\x1b[0m`);
+}
+
+function notice (msg) {
+  return console.log(`[HostJS \x1b[32mNotice\x1b[0m]: \x1b[32m${msg}\x1b[0m`)
+}
+
+function log (msg) {
+  return console.log(msg);
+}
+
+function warn (msg) {
+  return console.log(`[HostJS \x1b[33mWarn\x1b[0m]: \x1b[33m${msg}\x1b[0m`)
+}
+
+const logger = {
+  skip,
+  error,
+  notice,
+  log,
+  warn
+}
+
+export { logger };

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;
 }