@heyputer/puter.js 1.0.0

package/src/lib/APICallLogger.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ * 
+ * This file is part of Puter.
+ * 
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+
+/**
+ * APICallLogger provides centralized logging for all API calls made by the puter-js SDK.
+ * It logs API calls in a simple format: service - operation - params - result
+ */
+class APICallLogger {
+    constructor(config = {}) {
+        this.config = {
+            enabled: config.enabled ?? false,
+            ...config
+        };
+    }
+
+    /**
+     * Updates the logger configuration
+     * @param {Object} newConfig - New configuration options
+     */
+    updateConfig(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+    }
+
+    /**
+     * Enables API call logging
+     */
+    enable() {
+        this.config.enabled = true;
+    }
+
+    /**
+     * Disables API call logging
+     */
+    disable() {
+        this.config.enabled = false;
+    }
+
+    /**
+     * Checks if logging is enabled for the current configuration
+     * @returns {boolean}
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+
+    /**
+     * Logs the completion of an API request in a simple format
+     * @param {Object} options - Request completion options
+     */
+    logRequest(options = {}) {
+        if (!this.isEnabled()) return;
+
+        const { 
+            service = 'unknown', 
+            operation = 'unknown',
+            params = {},
+            result = null,
+            error = null
+        } = options;
+
+        // Format params as a readable string
+        let paramsStr = '{}';
+        if (params && Object.keys(params).length > 0) {
+            try {
+                paramsStr = JSON.stringify(params);
+            } catch (e) {
+                paramsStr = '[Unable to serialize params]';
+            }
+        }
+
+        // Format the log message with bold params
+        const logMessage = `${service} - ${operation} - \x1b[1m${paramsStr}\x1b[22m`;
+        
+        if (error) {
+            console.error(logMessage, { error: error.message || error, result });
+        } else {
+            console.log(logMessage, result);
+        }
+    }
+
+    /**
+     * Gets current logging statistics
+     * @returns {Object}
+     */
+    getStats() {
+        return {
+            enabled: this.config.enabled,
+            config: { ...this.config }
+        };
+    }
+}
+
+export default APICallLogger;

package/src/lib/EventListener.js

@@ -0,0 +1,51 @@
+export default class EventListener {
+    // Array of all supported event names.
+    #eventNames;
+
+    // Map of eventName -> array of listeners
+    #eventListeners;
+
+    constructor(eventNames) {
+        this.#eventNames = eventNames;
+
+        this.#eventListeners = (() => {
+            const map = new Map();
+            for (let eventName of this.#eventNames) {
+                map[eventName] = [];
+            }
+            return map;
+        })();
+    }
+
+    emit(eventName, data) {
+        if (!this.#eventNames.includes(eventName)) {
+            console.error(`Event name '${eventName}' not supported`);
+            return;
+        }
+        this.#eventListeners[eventName].forEach((listener) => {
+            listener(data);
+        });
+    }
+
+    on(eventName, callback) {
+        if (!this.#eventNames.includes(eventName)) {
+            console.error(`Event name '${eventName}' not supported`);
+            return;
+        }
+        this.#eventListeners[eventName].push(callback);
+        return this;
+    }
+
+    off(eventName, callback) {
+        if (!this.#eventNames.includes(eventName)) {
+            console.error(`Event name '${eventName}' not supported`);
+            return;
+        }
+        const listeners = this.#eventListeners[eventName];
+        const index = listeners.indexOf(callback)
+        if (index !== -1) {
+            listeners.splice(index, 1);
+        }
+        return this;
+    }
+}

package/src/lib/RequestError.js

@@ -0,0 +1,6 @@
+export class RequestError extends Error {
+    constructor (message) {
+        super(message);
+        this.name = 'RequestError'; // thanks minifier
+    }
+}

package/src/lib/filesystem/APIFS.js

@@ -0,0 +1,73 @@
+import * as utils from '../utils.js';
+import putility from "@heyputer/putility";
+import { TeePromise } from "@heyputer/putility/src/libs/promise.js";
+import getAbsolutePathForApp from '../../modules/FileSystem/utils/getAbsolutePathForApp.js';
+import { TFilesystem } from './definitions.js';
+
+export class PuterAPIFilesystem extends putility.AdvancedBase {
+    constructor ({ api_info }) {
+        super();
+        this.api_info = api_info;
+    }
+
+    static IMPLEMENTS = {
+        [TFilesystem]: {
+            stat: async function (options) {
+                this.ensure_auth_();
+                const tp = new TeePromise();
+
+
+                const xhr = new utils.initXhr('/stat', this.api_info.APIOrigin, undefined, "post", "text/plain;actually=json");
+                utils.setupXhrEventHandlers(xhr, undefined, undefined,
+                    tp.resolve.bind(tp),
+                    tp.reject.bind(tp),
+                );
+
+                let dataToSend = {};
+                if (options.uid !== undefined) {
+                    dataToSend.uid = options.uid;
+                } else if (options.path !== undefined) {
+                    // If dirPath is not provided or it's not starting with a slash, it means it's a relative path
+                    // in that case, we need to prepend the app's root directory to it
+                    dataToSend.path = getAbsolutePathForApp(options.path);
+                }
+
+                dataToSend.return_subdomains = options.returnSubdomains;
+                dataToSend.return_permissions = options.returnPermissions;
+                dataToSend.return_versions = options.returnVersions;
+                dataToSend.return_size = options.returnSize;
+                dataToSend.auth_token = this.api_info.authToken;
+
+
+                xhr.send(JSON.stringify(dataToSend));
+
+                return await tp;
+            },
+            readdir: async function (options) {
+                this.ensure_auth_();
+                const tp = new TeePromise();
+
+                const xhr = new utils.initXhr('/readdir', this.api_info.APIOrigin, undefined, "post", "text/plain;actually=json");
+                utils.setupXhrEventHandlers(xhr, undefined, undefined,
+                    tp.resolve.bind(tp),
+                    tp.reject.bind(tp),
+                );
+
+                xhr.send(JSON.stringify({ path: getAbsolutePathForApp(options.path), auth_token: this.api_info.authToken }));
+
+                return await tp;
+            },
+        }
+    }
+
+    ensure_auth_ () {
+        // TODO: remove reference to global 'puter'; get 'env' via context
+        if ( ! this.api_info.authToken && puter.env === 'web' ) {
+            try {
+                this.ui.authenticateWithPuter();
+            } catch (e) {
+                throw new Error('Authentication failed.');
+            }
+        }
+    }
+}

package/src/lib/filesystem/CacheFS.js

@@ -0,0 +1,243 @@
+import putility from "@heyputer/putility";
+import { RWLock } from "@heyputer/putility/src/libs/promise.js";
+import { ProxyFilesystem, TFilesystem } from "./definitions.js";
+import { uuidv4 } from "../utils.js";
+
+export const ROOT_UUID = '00000000-0000-0000-0000-000000000000';
+const TTL = 5 * 1000;
+
+export class CacheFS extends putility.AdvancedBase {
+    static PROPERTIES = {
+        assocs_path_: () => ({}),
+        assocs_uuid_: () => ({}),
+        entries: () => ({}),
+    };
+
+    get_entry_ei (external_identifier) {
+        if ( Array.isArray(external_identifier) ) {
+            for ( const ei of external_identifier ) {
+                const entry = this.get_entry_ei(ei);
+                if ( entry ) return entry;
+            }
+            return;
+        }
+
+        console.log('GET ENTRY EI', external_identifier);
+
+        const internal_identifier =
+            this.assocs_path_[external_identifier] ||
+            this.assocs_uuid_[external_identifier] ||
+            external_identifier;
+
+        if ( ! internal_identifier ) {
+            return;
+        }
+        return this.entries[internal_identifier];
+    }
+
+    add_entry ({ id } = {}) {
+        const internal_identifier = id ?? uuidv4();
+        const entry = {
+            id: internal_identifier,
+            stat_has: {},
+            stat_exp: 0,
+            locks: {
+                stat: new RWLock(),
+                members: new RWLock(),
+            },
+        };
+        this.entries[internal_identifier] = entry;
+        return entry;
+    }
+
+    assoc_path (path, internal_identifier) {
+        console.log('ASSOC PATH', path, internal_identifier);
+        this.assocs_path_[path] = internal_identifier;
+    }
+
+    assoc_uuid (uuid, internal_identifier) {
+        if ( uuid === internal_identifier ) return;
+        this.assocs_uuid_[uuid] = internal_identifier;
+    }
+    
+}
+
+export class CachedFilesystem extends ProxyFilesystem {
+    constructor (o) {
+        super(o);
+        // this.cacheFS = cacheFS;
+        this.cacheFS = new CacheFS();
+    }
+    static IMPLEMENTS = {
+        [TFilesystem]: {
+            stat: async function (o) {
+                let cent = this.cacheFS.get_entry_ei(o.path ?? o.uid);
+
+                const modifiers = [
+                    'subdomains',
+                    'permissions',
+                    'versions',
+                    'size',
+                ];
+
+                let values_requested = {};
+                for ( const mod of modifiers ) {
+                    const optionsKey = 'return' +
+                        mod.charAt(0).toUpperCase() +
+                        mod.slice(1);
+                    if ( ! o[optionsKey] ) continue;
+                    values_requested[mod] = true;
+                }
+
+                const satisfactory_cache = cent => {
+                    for ( const mod of modifiers ) {
+                        if ( ! values_requested[mod] ) continue;
+                        if ( ! cent.stat_has[mod] ) {
+                            return false;
+                        }
+                    }
+                    return true;
+                }
+                
+                let cached_stat;
+                if ( cent && cent.stat && cent.stat_exp > Date.now() ) {
+                    const l = await cent.locks.stat.rlock();
+                    if ( satisfactory_cache(cent) ) {
+                        cached_stat = cent.stat;
+                    }
+                    l.unlock();
+                }
+
+                if ( cached_stat ) {
+                    console.log('CACHE HIT');
+                    return cached_stat;
+                }
+                console.log('CACHE MISS');
+
+                let l;
+                if ( cent ) {
+                    l = await cent.locks.stat.wlock();
+                }
+
+                console.log('DOING THE STAT', o);
+                const entry = await this.delegate.stat(o);
+
+                // We might have new information to identify a relevant cache entry
+                let cent_replaced = !! cent;
+                cent = this.cacheFS.get_entry_ei([entry.uid, entry.path]);
+                if ( cent ) {
+                    if ( cent_replaced ) l.unlock();
+                    l = await cent.locks.stat.wlock();
+                }
+
+                if ( ! cent ) {
+                    cent = this.cacheFS.add_entry({ id: entry.uid });
+                    this.cacheFS.assoc_path(entry.path, cent.id);
+                    this.cacheFS.assoc_uuid(entry.uid, cent.id);
+                    
+                    l = await cent.locks.stat.wlock();
+                }
+
+                cent.stat = entry;
+                cent.stat_has = { ...values_requested };
+                // TODO: increase cache TTL once invalidation works
+                cent.stat_exp = Date.now() + TTL;
+
+                l.unlock();
+
+                console.log('RETRUNING THE ENTRY', entry);
+                return entry;
+            },
+            readdir: async function (o) {
+                let cent = this.cacheFS.get_entry_ei([o.path, o.uid]);
+
+                console.log('CENT', cent, o);
+                let stats = null;
+                if ( cent && cent.members && cent.members_exp > Date.now() ) {
+                    console.log('MEMBERS', cent.members);
+                    stats = [];
+                    const l = await cent.locks.stat.rlock();
+
+                    for ( const id of cent.members ) {
+                        const member = this.cacheFS.get_entry_ei(id);
+                        if ( ! member || ! member.stat || member.stat_exp <= Date.now() ) {
+                            console.log('NO MEMBER OR STAT', member);
+                            stats = null;
+                            break;
+                        }
+                        console.log('member', member);
+                        if ( ! o.no_assocs && ! member.stat_has.subdomains ) {
+                            stats = null;
+                            break;
+                        }
+                        if ( ! o.no_assocs && ! member.stat_has.apps ) {
+                            stats = null;
+                            break;
+                        }
+                        if ( ! o.no_thumbs && ! member.stat_has.thumbnail ) {
+                            stats = null;
+                            break;
+                        }
+                        console.log('PUSHING', member.stat);
+
+                        stats.push(member.stat);
+                    }
+
+                    l.unlock();
+                }
+
+                console.log('STATS????', stats);
+                if ( stats ) {
+                    return stats;
+                }
+
+                let l;
+                if ( cent ) {
+                    l = await cent.locks.members.wlock();
+                }
+
+                const entries = await this.delegate.readdir(o);
+                if ( ! cent ) {
+                    cent = this.cacheFS.add_entry(o.uid ? { id: o.uid } : {});
+                    if ( o.path ) this.cacheFS.assoc_path(o.path, cent.id);
+                    l = await cent.locks.members.wlock();
+                }
+
+                let cent_ids = [];
+                for ( const entry of entries ) {
+                    let entry_cent = this.cacheFS.get_entry_ei([entry.path, entry.uid]);
+                    if ( ! entry_cent ) {
+                        entry_cent = this.cacheFS.add_entry({ id: entry.uid });
+                        this.cacheFS.assoc_path(entry.path, entry.uid);
+                    }
+                    cent_ids.push(entry_cent.id);
+                    // TODO: update_stat_ is not implemented
+                    // this.cacheFS.update_stat_(entry_cent, entry, {
+                    //     subdomains: ! o.no_assocs,
+                    //     apps: ! o.no_assocs,
+                    //     thumbnail: ! o.no_thumbs,
+                    // });
+                    entry_cent.stat = entry;
+                    entry_cent.stat_has = {
+                        subdomains: ! o.no_assocs,
+                        apps: ! o.no_assocs,
+                        thumbnail: ! o.no_thumbs,
+                    }
+                    entry_cent.stat_exp = Date.now() + 1000*3;
+                }
+
+                cent.members = []
+                for ( const id of cent_ids ) {
+                    cent.members.push(id);
+                }
+                cent.members_exp = Date.now() + TTL;
+
+                l.unlock();
+
+                console.log('CACHE ENTRY?', cent);
+
+                return entries;
+            }
+        }
+    }
+}

package/src/lib/filesystem/PostMessageFS.js

@@ -0,0 +1,40 @@
+import putility from "@heyputer/putility";
+import { TFilesystem } from "./definitions.js";
+
+const example =     {
+        "id": "f485f1ba-de07-422c-8c4b-c2da057d4a44",
+        "uid": "f485f1ba-de07-422c-8c4b-c2da057d4a44",
+        "is_dir": true,
+        "immutable": true,
+        "name": "Test",
+    };
+
+export class PostMessageFilesystem extends putility.AdvancedBase {
+    constructor ({ rpc, messageTarget }) {
+        super();
+        this.rpc = rpc;
+        this.messageTarget = messageTarget;
+    }
+    static IMPLEMENTS = {
+        [TFilesystem]: {
+            stat: async function (o) {
+                return example;
+            },
+            readdir: async function (o) {
+                const tp = new putility.libs.promise.TeePromise();
+                const $callback = this.rpc.registerCallback((result) => {
+                    tp.resolve(result);
+                });
+                // return [example];
+                this.messageTarget.postMessage({
+                    $: 'puter-fs',
+                    $callback,
+                    op: 'readdir',
+                    args: o,
+                }, '*');
+
+                return await tp;
+            }
+        }
+    }
+}

package/src/lib/filesystem/definitions.js

@@ -0,0 +1,39 @@
+import putility from "@heyputer/putility";
+
+export const TFilesystem = 'TFilesystem';
+
+// TODO: UNUSED (eventually putility will support these definitions)
+//       This is here so that the idea is not forgotten.
+export const IFilesystem = {
+    methods: {
+        stat: {
+            parameters: {
+                path: {
+                    alias: 'uid',
+                }
+            }
+        }
+    }
+
+};
+
+export class ProxyFilesystem extends putility.AdvancedBase {
+    static PROPERTIES = {
+        delegate: () => {}, 
+    }
+    // TODO: constructor implied by properties
+    constructor ({ delegate }) {
+        super();
+        this.delegate = delegate;
+    }
+    static IMPLEMENTS = {
+        [TFilesystem]: {
+            stat: async function (o) {
+                return this.delegate.stat(o);
+            },
+            readdir: async function (o) {
+                return this.delegate.readdir(o);
+            }
+        }
+    }
+}