@nosana/node 1.0.0-rc

package/README.md

@@ -0,0 +1,92 @@
+# Nosana NODE
+
+The Nosana NODE is a command-line tool for interacting with the [Nosana Network](https://nosana.com), enabling users to run a Nosana Node.
+
+---
+
+## Features
+
+- **Run a Node**: Set up and manage a Nosana Node.
+
+## Install
+
+```shell
+$ npm install -g @nosana/node
+
+# or install with yarn
+$ yarn global add @nosana/node
+```
+
+**HINT**\
+Alternatively, you can use `npx` to use the node directly without installing it globally:
+
+```shell
+$ npx @nosana/node help
+```
+
+## Basic Usage
+
+Once installed, you can invoke NODE commands directly from your OS command line through the `nosana-node` executable. See the available commands by entering the following:
+
+```shell
+$ nosana-node help
+```
+
+All interactions with Nosana NODE are of the form
+
+```shell
+$ nosana [command] [options] [argument]
+```
+
+Available `node` commands:
+
+```
+node start [options] <market>             Start Nosana Node
+node run [options] <job-definition-file>  Run Job Definition File
+node help [command]                       display help for command
+```
+
+Global options:
+
+```
+-V, --version                        output the version number
+-n, --network <network>              network to run on (choices: "devnet", "mainnet", default: "mainnet")
+--rpc <url>                          RPC node to use
+--log <logLevel>                     Log level (choices: "info", "none", "debug", "trace", default: "debug")
+```
+
+## Start a Nosana Node
+
+To get started with your Nosana Node on the Nosana Grid, you can run a node after you've installed the prerequisites with the following command:
+
+`nosana node start [options]`
+
+Options:
+
+```
+  --provider <provider>     provider used to run the job (choices: "docker", "podman", default: "podman")
+  -w, --wallet <wallet>     path to wallet private key (default: "~/.nosana/nosana_key.json")
+  --docker, --podman <URI>  Podman/Docker connection URI (default: "~/.nosana/podman/podman.sock")
+  -h, --help                display help for command
+```
+
+## Starting node
+
+With the `nosana node start [options]` command you can start a Nosana Node and join the Nosana Network.
+
+Options:
+
+```
+  --provider <provider>     provider used to run the job (choices: "docker", "podman", default: "podman")
+  -w, --wallet <wallet>     path to wallet private key (default: "~/.nosana/nosana_key.json")
+  --docker, --podman <URI>  Podman/Docker connection URI (default: "~/.nosana/podman/podman.sock")
+  -h, --help                display help for command
+```
+
+## Documentation
+
+Please [visit our documentation](https://learn.nosana.com/) for a full list of commands and examples.
+
+For technical details on how the Nosana NODE works, refer to the technical documentation:
+
+[Technical Documentation](https://github.com/nosana-ci/nosana-node/tree/main/docs)

package/dist/.env

@@ -0,0 +1,7 @@
+BACKEND_SOLANA_ADDRESS=7rFPFnxjXHC2sfDy3qrDa9pEb4j49oivMuV7e8sYDPmB
+FRPC_CONTAINER_IMAGE=registry.hub.docker.com/nosana/frpc:v1.0.32
+FRP_SERVER_IMAGE=registry.hub.docker.com/nosana/frpc:v1.0.32
+FRP_SERVER_PORT=7000
+MIN_DISK_SPACE=25
+SIGN_MESSAGE="Hello Nosana Node!"
+API_PORT=8123

package/dist/.env.dev

@@ -0,0 +1,5 @@
+BACKEND_URL=https://dashboard.k8s.dev.nos.ci/api
+BACKEND_AUTHORIZATION_ADDRESS=3R1YEz9crQR3tRbtSAuufjSsjQXMqtDr1D4f1YprMUSE
+EXPLORER_URL=https://devnet.nosana.io
+FRP_SERVER_ADDRESS=node.k8s.dev.nos.ci
+MIN_DISK_SPACE=20

package/dist/.env.prd

@@ -0,0 +1,4 @@
+BACKEND_URL=https://dashboard.k8s.prd.nos.ci/api
+BACKEND_AUTHORIZATION_ADDRESS=FEEw3nDocYSyrLT4HPjibjYuaNekakWNmasNvEx3nHKi
+EXPLORER_URL=https://explore.nosana.com
+FRP_SERVER_ADDRESS=node.k8s.prd.nos.ci

package/dist/NodeManager/client/index.d.ts

@@ -0,0 +1,4 @@
+import createClient from 'openapi-fetch';
+import { paths } from './schema.js';
+export type QueryClient = ReturnType<typeof createClient<paths>>;
+export declare const clientSelector: () => QueryClient;

package/dist/NodeManager/client/index.js

@@ -0,0 +1,14 @@
+import createClient from 'openapi-fetch';
+import { configs } from '../configs/configs.js';
+export const clientSelector = () => {
+    let instance = undefined;
+    if (!instance) {
+        instance = createClient({
+            baseUrl: configs().backendUrl?.replace('/api', '') || '',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    return instance;
+};

package/dist/NodeManager/configs/NodeConfigs.d.ts

@@ -0,0 +1,14 @@
+export declare class NodeConfigs {
+    private options;
+    constructor(options: {
+        [key: string]: any;
+    });
+    loadVariablesToEnv(): void;
+}
+export declare class NodeConfigsSingleton {
+    private static instance;
+    private constructor();
+    static getInstance(options?: {
+        [key: string]: any;
+    }): NodeConfigs;
+}

package/dist/NodeManager/configs/NodeConfigs.js

@@ -0,0 +1,32 @@
+import dotenv from 'dotenv';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+export class NodeConfigs {
+    constructor(options) {
+        this.options = options;
+    }
+    loadVariablesToEnv() {
+        const network = this.options.network ? this.options.network : 'mainnet';
+        const env = network === 'mainnet' ? 'prd' : 'dev';
+        const modulePath = dirname(fileURLToPath(import.meta.url));
+        // Load .env.${env} first (higher priority)
+        dotenv.config({
+            path: [
+                resolve(modulePath, `../../../.env.${env}`),
+                resolve(modulePath, `../../../.env`),
+            ],
+        });
+        // System env vars have highest priority (never overwritten due to default override: false)
+    }
+}
+export class NodeConfigsSingleton {
+    constructor() { }
+    static getInstance(options) {
+        if (!NodeConfigsSingleton.instance) {
+            NodeConfigsSingleton.instance = new NodeConfigs(options || {});
+            NodeConfigsSingleton.instance.loadVariablesToEnv();
+        }
+        return NodeConfigsSingleton.instance;
+    }
+}
+NodeConfigsSingleton.instance = null;

package/dist/NodeManager/configs/__tests__/NodeConfigs.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/NodeManager/configs/__tests__/NodeConfigs.spec.js

@@ -0,0 +1,161 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import dotenv from 'dotenv';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Read .env files directly to avoid duplicating values
+const modulePath = path.dirname(fileURLToPath(import.meta.url));
+const envBase = dotenv.parse(fs.readFileSync(path.resolve(modulePath, '../../../../.env')));
+const envDev = dotenv.parse(fs.readFileSync(path.resolve(modulePath, '../../../../.env.dev')));
+const envProd = dotenv.parse(fs.readFileSync(path.resolve(modulePath, '../../../../.env.prd')));
+// Test constants for env variable names
+const ENV_VAR_BACKEND_SOLANA_ADDRESS = 'BACKEND_SOLANA_ADDRESS';
+const ENV_VAR_BACKEND_URL = 'BACKEND_URL';
+const ENV_VAR_MIN_DISK_SPACE = 'MIN_DISK_SPACE';
+const DEVNET = 'devnet';
+const MAINNET = 'mainnet';
+describe('NodeConfigs', () => {
+    let originalEnv;
+    beforeEach(() => {
+        originalEnv = { ...process.env };
+        vi.resetModules();
+        // Clear all relevant env vars to ensure clean state
+        delete process.env.APP_ENV;
+        delete process.env.NODE_ENV;
+        delete process.env.BACKEND_URL;
+        delete process.env.BACKEND_SOLANA_ADDRESS;
+        delete process.env.BACKEND_AUTHORIZATION_ADDRESS;
+        delete process.env.EXPLORER_URL;
+        delete process.env.SIGN_MESSAGE;
+        delete process.env.FRP_SERVER_ADDRESS;
+        delete process.env.FRP_SERVER_PORT;
+        delete process.env.FRPC_CONTAINER_IMAGE;
+        delete process.env.FRP_SERVER_IMAGE;
+        delete process.env.API_PORT;
+        delete process.env.MIN_DISK_SPACE;
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    describe('dotenv file merging', () => {
+        it('should load common variables from base .env file', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: MAINNET });
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_SOLANA_ADDRESS]).toBe(envBase[ENV_VAR_BACKEND_SOLANA_ADDRESS]);
+        });
+        it('should load environment-specific variables', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: DEVNET });
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envDev[ENV_VAR_BACKEND_URL]);
+        });
+        it('should override common values with environment-specific values', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: DEVNET });
+            nodeConfigs.loadVariablesToEnv();
+            // MIN_DISK_SPACE exists in both .env (base) and .env.dev
+            // With override:true and env-specific file loaded last, development value should win
+            expect(process.env[ENV_VAR_MIN_DISK_SPACE]).toBe(envDev[ENV_VAR_MIN_DISK_SPACE]);
+        });
+        it('should use common value when environment-specific file does not override it', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: MAINNET });
+            nodeConfigs.loadVariablesToEnv();
+            // MIN_DISK_SPACE only has override in .env.dev, not in .env.prd
+            // So production should use the base .env value
+            expect(process.env[ENV_VAR_MIN_DISK_SPACE]).toBe(envBase[ENV_VAR_MIN_DISK_SPACE]);
+        });
+    });
+    describe('network to environment mapping', () => {
+        it('should use prd environment for mainnet network', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: MAINNET });
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envProd[ENV_VAR_BACKEND_URL]);
+        });
+        it('should use dev environment for devnet network', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: DEVNET });
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envDev[ENV_VAR_BACKEND_URL]);
+        });
+        it('should use dev environment when network is not mainnet', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({ network: 'testnet' });
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envDev[ENV_VAR_BACKEND_URL]);
+        });
+        it('should default to mainnet (prd) when network is not specified', async () => {
+            const { NodeConfigs } = await import('../NodeConfigs.js');
+            const nodeConfigs = new NodeConfigs({});
+            nodeConfigs.loadVariablesToEnv();
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envProd[ENV_VAR_BACKEND_URL]);
+        });
+    });
+    describe('NodeConfigsSingleton', () => {
+        it('should only call loadVariablesToEnv once across multiple getInstance calls', async () => {
+            const { NodeConfigsSingleton, NodeConfigs } = await import('../NodeConfigs.js');
+            const loadSpy = vi.spyOn(NodeConfigs.prototype, 'loadVariablesToEnv');
+            NodeConfigsSingleton.getInstance({ network: DEVNET });
+            NodeConfigsSingleton.getInstance({ network: MAINNET });
+            NodeConfigsSingleton.getInstance();
+            expect(loadSpy).toHaveBeenCalledTimes(1);
+        });
+        it('should use options from first getInstance call', async () => {
+            const { NodeConfigsSingleton } = await import('../NodeConfigs.js');
+            // First call with devnet
+            NodeConfigsSingleton.getInstance({ network: DEVNET });
+            // Subsequent calls with different options should not change the config
+            NodeConfigsSingleton.getInstance({ network: MAINNET });
+            // Should still have dev environment values from first call
+            expect(process.env[ENV_VAR_BACKEND_URL]).toBe(envDev[ENV_VAR_BACKEND_URL]);
+        });
+    });
+    describe('startup without exceptions', () => {
+        it('should load configs for mainnet without throwing when all required variables have defaults', async () => {
+            // Clear all config-related environment variables to test defaults
+            delete process.env.APP_ENV;
+            delete process.env.NODE_ENV;
+            delete process.env.BACKEND_URL;
+            delete process.env.BACKEND_SOLANA_ADDRESS;
+            delete process.env.BACKEND_AUTHORIZATION_ADDRESS;
+            delete process.env.EXPLORER_URL;
+            delete process.env.SIGN_MESSAGE;
+            delete process.env.FRP_SERVER_ADDRESS;
+            delete process.env.FRP_SERVER_PORT;
+            delete process.env.FRPC_CONTAINER_IMAGE;
+            delete process.env.FRP_SERVER_IMAGE;
+            delete process.env.API_PORT;
+            delete process.env.MIN_DISK_SPACE;
+            // Attempt to load configs - should not throw
+            const { configs } = await import('../configs.js');
+            const config = configs({ network: MAINNET });
+            // Verify config object exists and has expected properties
+            expect(config).toBeDefined();
+            expect(config.network).toBe(MAINNET);
+        });
+        it('should load configs for devnet without throwing when all required variables have defaults', async () => {
+            // Clear all config-related environment variables to test defaults
+            delete process.env.APP_ENV;
+            delete process.env.NODE_ENV;
+            delete process.env.BACKEND_URL;
+            delete process.env.BACKEND_SOLANA_ADDRESS;
+            delete process.env.BACKEND_AUTHORIZATION_ADDRESS;
+            delete process.env.EXPLORER_URL;
+            delete process.env.SIGN_MESSAGE;
+            delete process.env.FRP_SERVER_ADDRESS;
+            delete process.env.FRP_SERVER_PORT;
+            delete process.env.FRPC_CONTAINER_IMAGE;
+            delete process.env.FRP_SERVER_IMAGE;
+            delete process.env.API_PORT;
+            delete process.env.MIN_DISK_SPACE;
+            // Attempt to load configs - should not throw
+            const { configs } = await import('../configs.js');
+            const config = configs({ network: DEVNET });
+            // Verify config object exists and has expected properties
+            expect(config).toBeDefined();
+            expect(config.network).toBe(DEVNET);
+        });
+    });
+});

package/dist/NodeManager/configs/configs.d.ts

@@ -0,0 +1,21 @@
+export type configType = {
+    isNodeRun: boolean;
+    backendUrl: string;
+    backendSolanaAddress: string;
+    backendAuthorizationAddress: string;
+    explorerUrl: string;
+    signMessage: string;
+    frp: {
+        serverAddr: string;
+        serverPort: number;
+        containerImage: string;
+    };
+    api: {
+        port: number;
+    };
+    minDiskSpace: number;
+    network: 'devnet' | 'mainnet';
+};
+export declare const configs: (options?: {
+    [key: string]: any;
+} | undefined) => configType;

package/dist/NodeManager/configs/configs.js

@@ -0,0 +1,23 @@
+import { NodeConfigsSingleton } from './NodeConfigs.js';
+import { loadConfigurationValue } from '../utils/utils.js';
+export const configs = (options) => {
+    NodeConfigsSingleton.getInstance(options);
+    return {
+        isNodeRun: options?.isNodeRun,
+        backendUrl: loadConfigurationValue('BACKEND_URL'),
+        backendSolanaAddress: loadConfigurationValue('BACKEND_SOLANA_ADDRESS'),
+        backendAuthorizationAddress: loadConfigurationValue('BACKEND_AUTHORIZATION_ADDRESS'),
+        explorerUrl: loadConfigurationValue('EXPLORER_URL'),
+        signMessage: loadConfigurationValue('SIGN_MESSAGE'),
+        frp: {
+            serverAddr: loadConfigurationValue('FRP_SERVER_ADDRESS'),
+            serverPort: parseInt(loadConfigurationValue('FRP_SERVER_PORT')),
+            containerImage: loadConfigurationValue('FRP_SERVER_IMAGE'),
+        },
+        api: {
+            port: parseInt(loadConfigurationValue('API_PORT')),
+        },
+        minDiskSpace: parseInt(loadConfigurationValue('MIN_DISK_SPACE')),
+        network: options?.network ?? 'mainnet',
+    };
+};

package/dist/NodeManager/db/__tests__/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/NodeManager/db/__tests__/index.spec.js

@@ -0,0 +1,65 @@
+import fs from 'fs';
+import { DB } from '../index.js';
+vi.mock('fs');
+vi.mock('os', () => ({
+    default: {
+        homedir: () => 'homedir',
+    },
+}));
+vi.mock('../../../static/index.js', () => ({
+    pkg: {
+        version: '0.0.0_TEST',
+    },
+}));
+describe('DB', () => {
+    const mock_mkdirSync = vi.fn();
+    beforeEach(() => {
+        fs.mkdirSync.mockImplementation((args1, args2) => mock_mkdirSync(args1, args2));
+    });
+    afterEach(() => {
+        mock_mkdirSync.mockReset();
+    });
+    it('should create db directory and return a DB instance', () => {
+        const result = new DB('test');
+        expect(mock_mkdirSync).toHaveBeenCalledTimes(1);
+        expect(mock_mkdirSync).toHaveBeenCalledWith('test', { recursive: true });
+        expect(result.db.data).toEqual({
+            resources: {
+                images: {},
+                volumes: {},
+            },
+            flows: {},
+            info: {
+                version: '0.0.0_TEST',
+                country: '',
+                network: {
+                    ip: '',
+                    ping_ms: 0,
+                    download_mbps: 0,
+                    upload_mbps: 0,
+                },
+                system_environment: '',
+                cpu: {
+                    model: '',
+                    physical_cores: 0,
+                    logical_cores: 0,
+                },
+                disk_gb: 0,
+                ram_mb: 0,
+                gpus: {
+                    devices: [],
+                    runtime_version: 0,
+                    cuda_driver_version: 0,
+                    nvml_driver_version: '0.0.0',
+                },
+                protocol: '',
+            },
+        });
+    });
+    test('when configLocation starts with ~ should replace with os.homedir', () => {
+        new DB('~/test');
+        expect(mock_mkdirSync).toHaveBeenCalledWith('homedir/test', {
+            recursive: true,
+        });
+    });
+});

package/dist/NodeManager/db/index.d.ts

@@ -0,0 +1,50 @@
+import { LowSync } from 'lowdb/lib';
+import { Flow } from '@nosana/sdk';
+import { CudaCheckSuccessResponse } from '../types/index.js';
+export type NodeDb = {
+    flows: {
+        [key: string]: Flow;
+    };
+    resources: Resources;
+    info: {
+        version: string;
+        country: string;
+        network: {
+            ip: string;
+            ping_ms: number;
+            download_mbps: number;
+            upload_mbps: number;
+        };
+        system_environment: string;
+        cpu: {
+            model: string;
+            physical_cores: number;
+            logical_cores: number;
+        };
+        disk_gb: number;
+        ram_mb: number;
+        gpus: CudaCheckSuccessResponse;
+        protocol: string;
+    };
+};
+export type Resources = {
+    images: {
+        [key: string]: ResourceHistory;
+    };
+    volumes: {
+        [key: string]: VolumeResource;
+    };
+};
+export type ResourceHistory = {
+    lastUsed: Date;
+    usage: number;
+    required: boolean;
+    isPrivate?: boolean;
+};
+export type VolumeResource = ResourceHistory & {
+    volume: string;
+};
+export declare class DB {
+    db: LowSync<NodeDb>;
+    constructor(configLocation: string);
+}

package/dist/NodeManager/db/index.js

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import os from 'os';
+import { JSONFileSyncPreset } from 'lowdb/node';
+import { pkg } from '../../static/index.js';
+const initial_state = {
+    resources: {
+        images: {},
+        volumes: {},
+    },
+    flows: {},
+    info: {
+        version: pkg.version,
+        country: '',
+        network: {
+            ip: '',
+            ping_ms: 0,
+            download_mbps: 0,
+            upload_mbps: 0,
+        },
+        system_environment: '',
+        cpu: {
+            model: '',
+            physical_cores: 0,
+            logical_cores: 0,
+        },
+        disk_gb: 0,
+        ram_mb: 0,
+        gpus: {
+            devices: [],
+            runtime_version: 0,
+            cuda_driver_version: 0,
+            nvml_driver_version: '0.0.0',
+        },
+        protocol: '',
+    },
+};
+export class DB {
+    constructor(configLocation) {
+        if (configLocation[0] === '~') {
+            configLocation = configLocation.replace('~', os.homedir());
+        }
+        fs.mkdirSync(configLocation, { recursive: true });
+        this.db = JSONFileSyncPreset(`${configLocation}/nosana_db.json`, initial_state);
+        if (!this.db.data.resources) {
+            this.db.data.resources = initial_state.resources;
+        }
+        if (!this.db.data.flows) {
+            this.db.data.flows = initial_state.flows;
+        }
+        if (!this.db.data.info) {
+            this.db.data.info = initial_state.info;
+        }
+        if (this.db.data.info) {
+            this.db.data.info = { ...initial_state.info, ...this.db.data.info };
+        }
+        // @ts-ignore
+        if (this.db.data.info.disk) {
+            // @ts-ignore
+            delete this.db.data.info.disk; // remove old key
+        }
+        this.db.data.info.version = pkg.version;
+        this.db.write();
+    }
+}

package/dist/NodeManager/errors/NodeAlreadyActiveError.d.ts

@@ -0,0 +1,3 @@
+export declare class NodeAlreadyActiveError extends Error {
+    constructor(address: string);
+}

package/dist/NodeManager/errors/NodeAlreadyActiveError.js

@@ -0,0 +1,6 @@
+export class NodeAlreadyActiveError extends Error {
+    constructor(address) {
+        super(`Node ${address} is already online and active; you cannot start a new one`);
+        this.name = 'NodeAlreadyActiveError';
+    }
+}

package/dist/NodeManager/index.d.ts

@@ -0,0 +1,24 @@
+export default class NodeManager {
+    private node;
+    private apiHandler;
+    private exiting;
+    inJobLoop: boolean;
+    constructor(options: {
+        [key: string]: any;
+    });
+    init(): Promise<void>;
+    start(marketArg?: string): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * clean is different from stop as it does not stop the API
+     * it doesn't quit a job or leave a market, it just clears instances from the handlers
+     */
+    clean(): Promise<void>;
+    restart(marketArg?: string): Promise<void>;
+    delay(sec: number): Promise<void>;
+    error(): Promise<void>;
+    /**
+     * Set up handling for process exit signals
+     */
+    private handleProcessExit;
+}