Connectors Reference

This page provides a detailed reference for the connector architecture in io-oidis-services. For the high-level LCP overview and creating new connectors, see LCP & RPC.

BaseConnector Architecture

BaseConnector is the abstract base class for all frontend connectors. It handles transport client creation, environment detection, error handling, and reconnection logic.

Construction Options (IConnectorOptions)

Option	Type	Default	Description
`clientType`	`WebServiceClientType`	auto-detected	Explicit client type override
`maxReconnectCount`	`number`	`0`	Max reconnection attempts (-1 = infinite)
`serverConfigurationSource`	`string \| WebServiceConfiguration`	—	Transport client configuration URL
`suppressInit`	`boolean`	`false`	Skip `init()` during construction
`reconnect`	`boolean`	`false`	Enable automatic reconnection

Client Type Auto-Detection

When no explicit clientType is provided, getClientType() inspects the runtime environment:

IsLocalhostHosting()  →  HOST_CLIENT
IsJre() / IsPlugin() / IsConnector()  →  DESKTOP_CONNECTOR
IsOnServer()  →  HUB_CONNECTOR
(fallback)  →  BUILDER_CONNECTOR

Namespace Mapping

Each connector overrides getServerNamespaces() to map client types to backend class namespaces:

protected getServerNamespaces() : any {
    const namespaces : any = {};
    namespaces[WebServiceClientType.HUB_CONNECTOR] = "Io.Oidis.Hub.Utils.MyManager";
    namespaces[WebServiceClientType.DESKTOP_CONNECTOR] = "Io.Oidis.Connector.Connectors.MyManager";
    return namespaces;
}

The connector resolves the namespace at init time and all subsequent invoke() calls target that backend class.

Invocation Methods

Method	API Style	Use Case
`invoke()`	Callback chain	Legacy code: `.DataFormatter().OnError().Then()`
`asyncInvoke()`	Promise/async-await	Modern code: `await this.asyncInvoke("Method", args)`
`toSyncInvoke()`	Promise → Callback bridge	Wrap async methods in the callback API
`progressWrapper()`	Promise + progress	Long-running operations with `OnChange` callbacks

Error Handling

ErrorPropagation(true) — Errors are logged as warnings (non-fatal)
ErrorPropagation(false) (default) — Errors throw global exceptions in production mode
Connection loss — For HUB/REST connectors without reconnect, redirects to /ServerError/Http/ConnectionLost
Reconnection — When enabled, auto-reconnects on timeout/close events

Hub Agent Forwarding

For distributed deployments, a connector can forward requests to a remote agent via Hub:

const connector = MyConnector.getClient();
connector.setAgent("remote-agent-name", "https://hub-url");
// All subsequent calls are forwarded through Hub to the remote agent

This changes the client type to FORWARD_CLIENT and routes requests through ForwardingClient.

Progress Reporting (IFetchProgress)

For long-running operations, progressWrapper() emits progress updates:

protected Download($url : string) : Promise<string> {
    return this.progressWrapper<string>("Download", [$url], ($progress) => {
        // $progress.index = current step
        // $progress.from = total steps
        // $progress.message = status text
    });
}

Connector Catalog

All 16 connectors in io-oidis-services, grouped by function.

System & Environment

Connector	Purpose	Key Methods
EnvironmentConnector	Backend environment state and initialization progress	`getEnvType()`, `IsEnvironmentLoaded()`, `getStateChain()`, `AddLoadingListener()`
UpdatesManagerConnector	Application update management	`CheckForUpdates()`, `InstallUpdate()`
CronConnector	Scheduled task management	`AddTask()`, `RemoveTask()`, `GetTasks()`

EnvironmentConnector caches a positive IsEnvironmentLoaded() / InitPageEnabled() result and the state chain only until the backend connection is closed or times out, so a restarted backend is checked again instead of being reported as loaded. getStateChain() returns IEnvironmentStep[] (state, label, route, failure); the end state is the last non-failure step and is application specific - see Hub Backend Overview.

File System & Terminal

Connector	Purpose	Key Methods
FileSystemHandlerConnector	File I/O, directories, downloads, archives	`Read()`, `Write()`, `Delete()`, `Copy()`, `Download()`, `Pack()`, `Unpack()`
TerminalConnector	Process execution and management	`Execute()`, `Spawn()`, `Elevate()`, `Kill()`
DialogsConnector	Native OS file/folder dialogs	`ShowFileDialog()`, `ShowSaveFileDialog()`, `ShowFileExplorer()`

Window & UI

Connector	Purpose	Key Methods
WindowHandlerConnector	Window management and system tray	`Close()`, `Minimize()`, `Maximize()`, `CreateNotifyIcon()`, `setTaskBarProgressState()`
IdeHandlerConnector	IDE integration	`OpenFile()`, `OpenProject()`

Networking & Communication

Connector	Purpose	Key Methods
NetworkingConnector	Network port operations	`getFreePort()`, `AddPortListener()`, `WriteToPort()`
AgentsRegisterConnector	Hub agent registration and messaging	`RegisterAgent()`, `ForwardMessage()`, `getAgentsList()`

Security & Auth

Connector	Purpose	Key Methods
AuthManagerConnector	Authentication, users, groups, tokens	`LogIn()`, `LogOut()`, `Register()`, `GenerateAuthToken()`
CertsConnector	SSL certificate management	`GenerateCert()`, `ImportCert()`

Interop & Reporting

Connector	Purpose	Key Methods
COMproxyConnector	COM proxy for Windows native components	`Invoke()`, `CreateInstance()`
FFIProxyConnector	Foreign Function Interface proxy	`Call()`, `LoadLibrary()`
VirtualBoxConnector	VirtualBox VM management	`Start()`, `Stop()`, `Execute()`, `Copy()`
ReportServiceConnector	Logging, email, crash reports	`LogIt()`, `SendMail()`, `CreateReport()`

Async Variants

Several connectors provide an *Async variant returning native Promises instead of callback chains:

FileSystemHandlerConnectorAsync
TerminalConnectorAsync
DialogsConnectorAsync
AgentsRegisterConnectorAsync

Detailed Connector Reference

FileSystemHandlerConnector

Wraps the backend FileSystemHandler service for local file I/O, directory operations, HTTP downloads, and archive management. Provides both callback (FileSystemHandlerConnector) and async (FileSystemHandlerConnectorAsync) variants through a shared BaseFileSystemHandlerConnector base.

Namespace mapping:

Client Type	Backend Namespace
`DESKTOP_CONNECTOR`	`Io.Oidis.Connector.Connectors.FileSystemHandler`
`BUILDER_CONNECTOR`	`Io.Oidis.Builder.Connectors.FileSystemHandler`
`FORWARD_CLIENT`	`Io.Oidis.Connector.Connectors.FileSystemHandler`
`HOST_CLIENT`	`Io.Oidis.Connector.Connectors.FileSystemHandler`

API overview:

Category	Methods
Path queries	`getTempPath()`, `getProjectBasePath()`, `getAppDataPath()`, `getLocalAppDataPath()`, `getHostLocation()`
Directory listing	`getPathMap()`, `getNetworkMap()`, `getDirectoryContent()`, `Expand()`
File operations	`Read()`, `Write()`, `Delete()`, `Exists()`, `IsFile()`, `IsEmpty()`, `Rename()`, `Copy()`, `CreateDirectory()`
Downloads	`Download()`, `AbortDownload()` — full lifecycle with `OnStart`/`OnChange`/`OnComplete`/`OnError`
Archives	`Pack()`, `Unpack()` — ZIP/TAR operations with output path and type options
Shortcuts	`CreateShortcut()`, `getLinkTargetPath()`

Download supports IFileSystemDownloadOptions for HTTP method, headers, body, proxy config, mTLS, and streaming mode.

TerminalConnector

Wraps the backend Terminal service for child process creation and management. Provides both callback and async variants.

Namespace mapping:

Client Type	Backend Namespace
`DESKTOP_CONNECTOR`	`Io.Oidis.Connector.Connectors.Terminal`
`BUILDER_CONNECTOR`	`Io.Oidis.Builder.Connectors.Terminal`
`FORWARD_CLIENT`	`Io.Oidis.Connector.Connectors.Terminal`
`HOST_CLIENT`	`Io.Oidis.Connector.Connectors.Terminal`

API overview:

Method	Description
`Execute()`	Run a command and wait for exit (returns exit code + stdout/stderr)
`Spawn()`	Run a command with streaming `OnMessage` events for stdout/stderr
`Elevate()`	Run a command with elevated (admin) privileges
`Open()`	Open a file/URL with the default OS handler
`Kill()`	Kill a process by path or name

All process methods accept ITerminalOptions for cwd, environment, shell mode, detach, and advanced settings (colored output, noExitOnStderr, stdin).

WindowHandlerConnector

Wraps the WindowHandler service for native window management, system tray icons, taskbar progress, file dialogs, and in-window script execution.

Namespace mapping:

Client Type	Backend Namespace
`CEF_QUERY`	`Io.Oidis.ChromiumRE.Connectors.WindowHandler`
`DESKTOP_CONNECTOR`	`Io.Oidis.Connector.Connectors.WindowHandler`

Client type auto-detection overrides the base: uses DESKTOP_CONNECTOR when a target PID/title is provided, otherwise falls back to CEF_QUERY for the hosting window.

API overview:

Category	Methods
Window state	`Close()`, `Minimize()`, `Maximize()`, `Restore()`, `Show()`, `Hide()`, `Exists()`, `getState()`
Window geometry	`MoveTo()`, `Resize()`, `CanResize()`
Child windows	`Open()`, `ScriptExecute()`, `getCookies()`, `ShowDebugConsole()`
System tray	`CreateNotifyIcon()`, `ModifyNotifyIcon()`, `DestroyNotifyIcon()`
Taskbar	`setTaskBarProgressState()`, `setTaskBarProgressValue()`
Dialogs	`ShowFileDialog()`
Events	`AddEventListener()`, `RemoveEventListener()`, `getEvents()`

Events include OnNotifyIconClick, OnNotifyIconDoubleClick, OnNotifyIconBalloonClick, OnNotifyIconContextItemSelected, and OnWindowChanged.

AuthManagerConnector

Wraps the Hub AuthManager service for user authentication, registration, password management, API token lifecycle, group/role authorization, and organization administration. Uses exclusively async invocation (asyncInvoke) and communicates only with Hub.

Namespace mapping:

Client Type	Backend Namespace
`HUB_CONNECTOR`	`Io.Oidis.Hub.Utils.AuthManager`

API overview:

Category	Methods
Authentication	`LogIn()`, `LogOut()`, `IsAuthenticated()`, `IsAuthorizedFor()`, `CurrentToken()`, `IsPasswordValid()`
User management	`Register()`, `ActivateUser()`, `DeactivateUser()`, `RemoveUser()`, `DeleteUser()`, `RestoreUser()`
Password	`ResetPassword()`, `ResetPasswordConfirm()`, `ChangePassword()`, `InvitationConfirm()`
Profiles	`getUserId()`, `getUserProfile()`, `setUserProfile()`, `FindUsers()`, `CheckEmailDuplicity()`
Groups	`AddGroup()`, `RemoveGroup()`, `getGroups()`, `CreateGroup()`, `FindGroups()`, `DeleteGroup()`, `RestoreGroup()`
Permissions	`getAuthorizedMethods()`, `setAuthorizedMethods()`, `getAuthorizedMethodsFor()`, `getGroupMethods()`
Auth tokens	`GenerateAuthToken()`, `RevokeAuthToken()`, `UpdateAuthToken()`, `getAuthToken()`, `IsAuthTokenValid()`
Applications	`RegisterApp()`, `getAppMethods()`
Organizations	`RegisterOrganization()`, `setOrganizationProfile()`, `getOrganizationProfile()`, `getOrganizationChart()`
Org members	`AddUserToOrganization()`, `RemoveUserFromOrganization()`, `FindOrganizations()`
Org lifecycle	`DeactivateOrganization()`, `DeleteOrganization()`, `RestoreOrganization()`

Security note: All password methods hash with SHA-1 on the client side before transmission.

Namespace Mapping Summary

Complete mapping of all 16 connectors to their backend class namespaces:

Connector	Client Type(s)	Backend Namespace(s)
AgentsRegisterConnector	HUB	`Io.Oidis.Hub.Primitives.AgentsRegister`
AuthManagerConnector	HUB	`Io.Oidis.Hub.Utils.AuthManager`
CertsConnector	HUB	`Io.Oidis.Hub.Connectors.CertsHandler`
COMproxyConnector	DESKTOP	`Io.Oidis.Connector.Connectors.COMproxy`
CronConnector	HUB	`Io.Oidis.Localhost.Utils.CronConnector`
DialogsConnector	DESKTOP, BUILDER	`Io.Oidis.Connector.Connectors.Dialogs`, `Io.Oidis.Builder.Connectors.Dialogs`
EnvironmentConnector	HUB	`Io.Oidis.Hub.Utils.EnvironmentHelper`
FFIProxyConnector	DESKTOP, BUILDER, FORWARD	`Io.Oidis.Connector.Connectors.FFIProxy`, `Io.Oidis.Builder.Connectors.FFIProxy`
FileSystemHandlerConnector	DESKTOP, BUILDER, FORWARD, HOST	`Io.Oidis.Connector.Connectors.FileSystemHandler`, `Io.Oidis.Builder.Connectors.FileSystemHandler`
IdeHandlerConnector	JXBROWSER_BRIDGE	`Io.Oidis.IdeJRE.Connectors.IdeHandler`
NetworkingConnector	DESKTOP, BUILDER, FORWARD	`Io.Oidis.Connector.Connectors.Network`, `Io.Oidis.Builder.Connectors.Network`
ReportServiceConnector	HUB	`Io.Oidis.Hub.Utils.ReportAPI`
TerminalConnector	DESKTOP, BUILDER, FORWARD, HOST	`Io.Oidis.Connector.Connectors.Terminal`, `Io.Oidis.Builder.Connectors.Terminal`
UpdatesManagerConnector	HUB	`Io.Oidis.Hub.Utils.SelfupdatesManager`
VirtualBoxConnector	BUILDER	`Io.Oidis.Builder.Connectors.VirtualBoxHandler`
WindowHandlerConnector	CEF_QUERY, DESKTOP	`Io.Oidis.ChromiumRE.Connectors.WindowHandler`, `Io.Oidis.Connector.Connectors.WindowHandler`

BaseConnector Architecture​

Construction Options (IConnectorOptions)​

Client Type Auto-Detection​

Namespace Mapping​

Invocation Methods​

Error Handling​

Hub Agent Forwarding​

Progress Reporting (IFetchProgress)​

Connector Catalog​

System & Environment​

File System & Terminal​

Window & UI​

Networking & Communication​

Security & Auth​

Interop & Reporting​

Async Variants​

Detailed Connector Reference​

FileSystemHandlerConnector​

TerminalConnector​

WindowHandlerConnector​

AuthManagerConnector​

Namespace Mapping Summary​

BaseConnector Architecture

Construction Options (IConnectorOptions)

Client Type Auto-Detection

Namespace Mapping

Invocation Methods

Error Handling

Hub Agent Forwarding

Progress Reporting (IFetchProgress)

Connector Catalog

System & Environment

File System & Terminal

Window & UI

Networking & Communication

Security & Auth

Interop & Reporting

Async Variants

Detailed Connector Reference

FileSystemHandlerConnector

TerminalConnector

WindowHandlerConnector

AuthManagerConnector

Namespace Mapping Summary