io-oidis-connector

Base project for building agent applications — reverse tunneling endpoints, automation runners, IoT members, data aggregators, and CLI tools. Extends io-oidis-localhost with agent mode, native dialogs, network tunneling, file transfer, and Hub integration.

Package Purpose

io-oidis-connector is a standalone HTTP server framework that adds agent capabilities on top of io-oidis-localhost:

Agent Mode — Register with Oidis Hub, receive forwarded requests, report status via heartbeat
Dual-Port HTTP Server — Separate ports for front-end hosting and REST/LCP services
File System — Extended file operations with native dialogs, shortcuts, drive discovery
Network Tunneling — Local port listening, data forwarding, proxy detection
File Transfer — Chunked upload/download protocol with progress callbacks
Terminal — Shell command execution, spawn, elevate, kill
System Fingerprinting — Hardware-based device identification (BIOS, motherboard, drives)

Dependency Position

io-oidis-commons ← io-oidis-services ← io-oidis-localhost ← io-oidis-connector
                                       ← io-oidis-gui ←↑

Connector depends on localhost, services, commons, and gui. Solution projects that act as agents inherit from io-oidis-connector instead of io-oidis-localhost.

Source Structure

source/typescript/Io/Oidis/Connector/
├── Connectors/
│   ├── Dialogs.ts               — Native file/save dialogs, file explorer
│   ├── FileSystemHandler.ts     — Extended file system operations (@Extern)
│   ├── FileTransferConnector.ts — Chunked file transfer protocol
│   ├── FileTransferHandler.ts   — File transfer chunking implementation
│   ├── HubConnector.ts          — Hub registration & reverse tunneling
│   ├── Network.ts               — Port listening, tunneling, proxy detection
│   └── Terminal.ts              — Shell command execution (@Extern)
├── HttpProcessor/
│   ├── HttpServer.ts            — Dual-port HTTP server
│   └── Resolvers/
│       ├── ConnectorResponse.ts — connector.config.jsonp endpoint
│       ├── FrontEndLoader.ts    — Front-end static content
│       └── LiveContentResolver.ts — Live protocol handler
├── Gui/
│   ├── Index.ts                 — GUI index page
│   ├── Loader.ts                — GUI loader
│   └── HttpProcessor/Resolvers/
│       └── XOriginInterface.ts  — Cross-origin REST interface
├── Interfaces/
│   └── IProject.ts              — Configuration interfaces
├── Structures/
│   └── ProgramArgs.ts           — CLI arguments parser
├── DAO/
│   └── Resources.ts             — Data access layer
├── Loader.ts                    — Main entry point (extends Localhost Loader)
├── FallbacksMapping.ts          — Legacy namespace compatibility
└── ForceCompile.ts              — Ensures all classes are compiled

Execution Modes

The connector supports four execution modes:

Mode	Trigger	Description
Server	(default)	HTTP server on services port, optional host port
Agent	`agent` CLI arg	Connects to Hub, registers, receives forwarded requests
Snippet	`snippet` CLI arg	Runs development test snippets, then exits
Headless	via `HeadlessSnippet`	CLI-only execution, no server

Agent Mode

When started with the agent argument, the connector:

Resolves Hub endpoint — from CLI --hub flag, config agent.hub, or hubLocations aliases (prod, eap, dev)
Gathers metadata — platform detection (win32/win64/linux/arm/arm64/mac64), system fingerprint, package info, optional process.env
Opens WebSocket to Hub — via HubConnector (extends AgentsRegisterConnector)
Calls RegisterAgent — sends credentials, capabilities, metadata
Receives authorized methods — Hub responds with whitelisted @Extern methods
Listens for forwarded requests — Hub proxies client requests through the WebSocket
Starts heartbeat — periodic UpdateAgentStatus calls to report health

Heartbeat

The heartbeat mechanism monitors agent health and supports automatic recovery:

interface IHeartbeat {
    enabled : boolean;        // Enable heartbeat monitoring
    exitOnError : boolean;    // Exit process on heartbeat failure (for restart policy)
    period : number;          // Heartbeat interval (ms)
    timeout : number;         // Timeout for status update response (ms)
    restartDelay : number;    // Delay before restart attempt (ms)
}

When a heartbeat times out or Hub requests a restart, the connector either restarts the process (if exitOnError is true, relying on external process manager) or reconnects the WebSocket.

System Fingerprint

A SHA-1 hash of hardware identifiers used for device identification and licensing:

SHA1(manufacturer + model + serial + uuid + biosVendor + biosVersion +
     biosReleaseDate + boardSerial + boardManufacturer + platform + arch + hddId)

Where hddId is the concatenated model+serial of all non-removable disks. Generated via the systeminformation package.

Dual-Port HTTP Server

The connector's HttpServer extends the localhost HTTP server to support two separate server instances:

Port	Default	Purpose
Services port	`8888`	REST API and LCP (Live Content Protocol) endpoints
Host port	`80` / `8080` / `8880` / `8088` / `8008`	Front-end web interface (optional, requires `--open-host`)

Port selection is automatic with fallback — if the configured port is busy, the server tries the next available port. When --open-host is not set, only the services port is started.

In non-debug mode, the server tracks connected clients and auto-exits when all clients disconnect.

Connectors

HubConnector

Extends AgentsRegisterConnector from io-oidis-services. Manages the WebSocket connection to Hub.

Method	Description
`RegisterAgent($capabilities)`	Register with Hub, receive forwarded requests via `OnMessage`
`InitPipe($pipeId)`	Establish a reverse tunnel pipe for port forwarding
`WriteToPipe($sourceClientId, $pipeId, $protocol)`	Send data through an established pipe
`UpdateAgentStatus($status)`	Heartbeat — report agent status to Hub

Hub endpoint resolution order: CLI --hub → config agent.hub → hubLocations[agent.hub].

FileSystemHandler

Extends the localhost FileSystemHandler with additional operations exposed via @Extern():

Navigation: getPathMap (drive listing), getDirectoryContent
CRUD: Exists, IsFile, IsDirectory, CreateDirectory, Rename, Delete
Content: Read, Write, ReadStream, WriteStream, Copy, Download
Archive: Pack, Unpack
Platform-specific: CreateShortcut (Windows .lnk files)

Network

Port listening and network tunneling with @Extern() methods:

Method	Description
`getFreePort()`	Returns an available port number
`AddPortListener($port)`	Start listening on a local port, returns session ID
`RemovePortListener($sessionId, $port)`	Stop listening
`WriteToPort($data, $port)`	Send base64-encoded data to a listened port
`IsPortFree($port)`	Check if a port is available
`IsProxyRequired()`	Detect if proxy is needed (pings `hub.oidis.io`)

Port listeners use TCP sockets with a 15-minute timeout. Multiple sessions can share a port listener.

FileTransferConnector

Chunked file transfer protocol with progress reporting:

Method	Description
`UploadFile($fileInfo, $sourcePath)`	Upload file in chunks with progress callbacks
`DownloadFile($fileInfo, $targetPath)`	Download file in chunks with progress callbacks

Both methods return an IFileTransferPromise with .OnMessage() (progress), .OnError(), and .Then() (complete) callbacks.

Dialogs

Native OS dialog support (async):

Method	Platforms	Description
`ShowFileDialog`	Win, Linux, Mac	File open dialog
`ShowSaveFileDialog`	Win, Linux, Mac	File save dialog
`ShowFileExplorer`	Win, Linux, Mac	Open file explorer at path

Platform implementations: Windows (native/PowerShell), Linux (kdialog), macOS (osascript).

Terminal

Shell command execution with @Extern(false) (limited external access):

Method	Description
`Execute`	Run command synchronously, return output
`Spawn`	Run command asynchronously
`Open`	Open file or application
`Elevate`	Run with elevated privileges (Windows)
`Kill`	Terminate a process

HTTP Resolvers

Resolver	Path	Description
`ConnectorResponse`	`/connector.config.jsonp`, `/connector.config.js`	Serves connector configuration
`LiveContentResolver`	`/liveContent/`	Routes live protocol requests to connectors
`FrontEndLoader`	`/`	Front-end HTML with license headers
`XOriginInterface`	`/index`, `/web/` (production)	Cross-origin REST service interface
`Gui/Index`	`/index`, `/web/` (dev)	Development GUI with test snippets

Live Content Protocol

The LiveContentResolver routes real-time requests to the appropriate connector:

{ "type": "FileSystemHandler", "args": { "type": "Exists", "value": "/path/to/file" } }
{ "type": "Cmd", "args": { "cmd": "dir", "args": [], "cwd": "C:\\" } }
{ "type": "Spawn", "args": { "cmd": "npm", "args": ["install"], "cwd": "." } }

Supported types: Cmd, Spawn, FileSystem, FileSystemHandler.

Configuration

IProject Interface

Extends the localhost IProject with agent-specific settings:

interface IProject extends Localhost.IProject {
    agent : IAgentConfiguration;
    hubLocations : IHubLocations;
    heartbeat : IHeartbeat;
}

interface IAgentConfiguration {
    name : string;               // Agent display name
    hub : string;                // Hub URL or alias (prod/eap/dev)
    credentials : ICredentials;  // userName, authToken
    poolName : string;           // Agent pool (default: "Default")
    tag : string;                // Descriptive tag
    configuration : any;         // Custom key-value metadata
    disableMetadataEnv : boolean; // Omit process.env from metadata
}

interface IHubLocations {
    prod : string;   // Production Hub URL
    eap : string;    // Early Access Program Hub URL
    dev : string;    // Development Hub URL
}

private.conf.jsonp Example

Io.Oidis.Builder.DAO.Resources.Data({
    $interface: "IProjectSolution",
    domain: {
        ports: { http: 8088 },
        ssl: false,
        csp: false
    },
    agent: {
        hub: "http://localhost:9010/",
        name: "my-agent",
        poolName: "myPool",
        tag: "My connector agent",
        configuration: {
            CUSTOM_KEY: "custom-value"
        },
        disableMetadataEnv: false
    },
    heartbeat: {
        enabled: true,
        exitOnError: true,
        period: 30000,
        timeout: 10000,
        restartDelay: 5000
    },
    hubLocations: {
        prod: "https://hub.oidis.io",
        eap: "https://hub.eap.oidis.io",
        dev: "http://localhost:9010"
    },
    logger: { debug: true }
});

CLI Arguments

Argument	Alias	Description
`-h`	`--help`	Print help
`-v`	`--version`	Print version
`-p`	`--path`	Print connector location
`--stop`	`-s`	Stop the server
`--open-host`	`-o`	Start the host (front-end) server
`agent`	—	Start in agent mode (connect to Hub)
`snippet`	—	Run development snippets
`--services-port=<n>`	—	Override services port (default: 8888)
`--host-port=<n>`	—	Override host port
`--name=<value>`	—	Agent name for Hub registration
`--hub=<value>`	—	Hub URL or alias (`prod`, `eap`, `dev`)
`--user=<value>`	`--username`	Hub account username
`--token=<value>`	`--authtoken`	Hub authorization token
`--groups=<value>`	—	Semicolon-separated group IDs
`--config-locations=<paths>`	—	Semicolon-separated connector.config.jsonp paths

Multi-Platform Support

Build Solutions

Solution	Description
`static`	Default — bundled static resources
`shared`	Shared dependencies mode
`app`	Application entry point
`arm`	32-bit ARM build
`arm64`	64-bit ARM build

Platform Detection

The connector detects the runtime platform and reports it during agent registration:

Platform	Condition
`win32` / `win64`	Windows
`linux64`	Linux (x86/x64)
`arm32` / `arm64`	Linux on ARM
`mac64`	macOS

Deployment

Deployment configuration in bin/project/configs/deploy.jsonp supports multi-platform targets with agent profiles:

Linux — app-linux-nodejs platform
Windows — app-win-nodejs platform
i.MX (ARM) — app-imx-nodejs platform

Each target can have multiple agent profiles (prod, eap, dev) for staged rollouts.

Legacy Support

FallbacksMapping.ts provides backward-compatible namespace aliases for the legacy Com.Wui.Framework.* namespace, mapping them to the current Io.Oidis.Connector.* namespace.

Package Purpose​

Dependency Position​

Source Structure​

Execution Modes​

Agent Mode​

Heartbeat​

System Fingerprint​

Dual-Port HTTP Server​

Connectors​

HubConnector​

FileSystemHandler​

Network​

FileTransferConnector​

Dialogs​

Terminal​

HTTP Resolvers​

Live Content Protocol​

Configuration​

IProject Interface​

private.conf.jsonp Example​

CLI Arguments​

Multi-Platform Support​

Build Solutions​

Platform Detection​

Deployment​

Legacy Support​