{"id":46638214,"url":"https://github.com/tetherto/miningos-tpl-wrk-thing","last_synced_at":"2026-03-08T02:13:09.933Z","repository":{"id":340876425,"uuid":"1129676298","full_name":"tetherto/miningos-tpl-wrk-thing","owner":"tetherto","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-26T23:02:53.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T05:35:01.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tetherto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T12:28:47.000Z","updated_at":"2026-02-26T23:02:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tetherto/miningos-tpl-wrk-thing","commit_stats":null,"previous_names":["tetherto/miningos-tpl-wrk-thing"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tetherto/miningos-tpl-wrk-thing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-tpl-wrk-thing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-tpl-wrk-thing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-tpl-wrk-thing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-tpl-wrk-thing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tetherto","download_url":"https://codeload.github.com/tetherto/miningos-tpl-wrk-thing/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-tpl-wrk-thing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30242406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-08T02:13:09.395Z","updated_at":"2026-03-08T02:13:09.923Z","avatar_url":"https://github.com/tetherto.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# miningos-tpl-wrk-thing\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Architecture](#architecture)\n    1. [Detailed Component Architecture](#detailed-component-architecture)\n    2. [Object Model](#object-model)\n    3. [Worker Types](#worker-types)\n3. [Core Concepts](#core-concepts)\n    1. [Thing](#thing)\n    2. [Tag System](#tag-system)\n    3. [Snapshot](#snapshot)\n4. [API Reference](#api-reference)\n    1. [Thing Management](#thing-management)\n    2. [Thing Operation](#thing-operation)\n    3. [Data Access](#data-access)\n       \n## Overview\n\nThe WrkProcVar class provides a comprehensive base implementation for managing abstract entities (“things”) in MiningOS. Originally designed for physical device management, the framework has proven flexible enough to handle various data sources and services critical to mining operations.\n\n## Architecture\n\n### Detailed Component Architecture:\n\n```mermaid\ngraph TB\n    subgraph \"Worker Process\"\n        RPC[RPC Interface\u003cbr/\u003enet_r0.rpcServer]\n        Worker[WrkProcVar\u003cbr/\u003e'Thing'\u003cbr/\u003eWorker Instance]\n        \n        subgraph \"Facilities Layer\"\n            Interval[Interval Facility\u003cbr/\u003e- collectSnaps\u003cbr/\u003e- rotateLogs\u003cbr/\u003e- setupThings\u003cbr/\u003e- refreshReplicaConf]\n            Scheduler[Scheduler Facility\u003cbr/\u003e- buildStats\u003cbr/\u003e- stat timeframes]\n            Store[Store Facilities\u003cbr/\u003e- store_s0: metadata\u003cbr/\u003e- store_s1: data]\n            Net[Network Facility\u003cbr/\u003e- RPC/DHT\u003cbr/\u003e- handleReply]\n        end\n        \n        subgraph \"Data Layer\"\n            Memory[Memory Cache\u003cbr/\u003e- things: object\u003cbr/\u003e- log: object\u003cbr/\u003e- log_cache: object\u003cbr/\u003e- log_map: object\u003cbr/\u003e- replica_conf]\n            \n            subgraph \"Hyperbee Storage\"\n                MainDB[(Main DB\u003cbr/\u003edb)]\n                Things[(things\u003cbr/\u003edb.sub)]\n                MetaLogs[(meta_logs_00\u003cbr/\u003edb.sub)]\n                TimeLogs[(Time-series Logs\u003cbr/\u003e- thing-5m-ID\u003cbr/\u003e- stat-TIMEFRAME)]\n            end\n        end\n        \n        RPC --\u003e|handles requests| Worker\n        Worker --\u003e|initializes via setInitFacs| Interval\n        Worker --\u003e|initializes via setInitFacs| Scheduler\n        Worker --\u003e|initializes via setInitFacs| Store\n        Worker --\u003e|initializes via setInitFacs| Net\n        \n        Worker --\u003e|reads/writes| Memory\n        Store --\u003e|getBee creates| MainDB\n        MainDB --\u003e|sub creates| Things\n        MainDB --\u003e|sub creates| MetaLogs\n        Store --\u003e|via lWrkFunLogs| TimeLogs\n        \n        Things --\u003e|setupThings reads into| Memory\n        Worker --\u003e|collectSnaps updates| Memory\n        Memory --\u003e|_storeThingDb writes to| Things\n    end\n    \n    subgraph \"Instance Variables\"\n        InstVars[Instance Variables\u003cbr/\u003e- _collectingSnaps: boolean\u003cbr/\u003e- _tsCollectSnap: timestamp\u003cbr/\u003e- _handler: proxy]\n        Worker --\u003e|maintains| InstVars\n    end\n    \n    subgraph \"External Connections\"\n        Devices[Thing Devices\u003cbr/\u003eDefined by subclasses:\u003cbr/\u003e- connectThing\u003cbr/\u003e- disconnectThing\u003cbr/\u003e- collectThingSnap]\n        \n        Worker --\u003e|delegates to subclass| Devices\n    end\n    \n    subgraph \"Replication System\"\n        Master[Master Node\u003cbr/\u003eFull read/write\u003cbr/\u003ectx.slave = false]\n        Slave[Slave Node\u003cbr/\u003eRead-only\u003cbr/\u003ectx.slave = true]\n        Discovery[Replica Discovery\u003cbr/\u003ereplicaDiscoveryKey\u003cbr/\u003elWrkFunReplica]\n        \n        Master --\u003e|hypercore replication| Slave\n        Discovery --\u003e|startReplica| Master\n        Discovery --\u003e|refreshReplicaConf| Slave\n        MainDB -.-\u003e|hypercore protocol| Master\n    end\n    \n    subgraph \"Hook System\"\n        Hooks[Subclass Hooks\u003cbr/\u003e- registerThingHook0\u003cbr/\u003e- updateThingHook0\u003cbr/\u003e- forgetThingHook0\u003cbr/\u003e- setupThingHook0]\n        Worker --\u003e|calls| Hooks\n    end\n    \n    style RPC fill:#1976d2,stroke:#0d47a1,color:#fff\n    style Worker fill:#388e3c,stroke:#1b5e20,color:#fff\n    style Memory fill:#f57c00,stroke:#e65100,color:#fff\n    style MainDB fill:#7b1fa2,stroke:#4a148c,color:#fff\n    style Things fill:#7b1fa2,stroke:#4a148c,color:#fff\n    style MetaLogs fill:#7b1fa2,stroke:#4a148c,color:#fff\n    style TimeLogs fill:#7b1fa2,stroke:#4a148c,color:#fff\n    style Interval fill:#303f9f,stroke:#1a237e,color:#fff\n    style Scheduler fill:#303f9f,stroke:#1a237e,color:#fff\n    style Store fill:#303f9f,stroke:#1a237e,color:#fff\n    style Net fill:#303f9f,stroke:#1a237e,color:#fff\n    style Master fill:#b71c1c,stroke:#7f0000,color:#fff\n    style Slave fill:#bf360c,stroke:#870000,color:#fff\n    style Discovery fill:#880e4f,stroke:#560027,color:#fff\n```\n\nThis comprehensive view reveals the complete system architecture including internal components and external integrations. The Facilities Layer provides pluggable services that workers initialize during startup via setInitFacs, including interval-based tasks (snapshot collection, log rotation, thing setup, and replica configuration refresh), scheduled statistics generation, network services with RPC/DHT capabilities, and distributed storage management. The dual-storage architecture separates volatile in-memory caches (containing things, logs, and replica configuration) from persistent Hyperbee databases, with time-series logs stored separately for efficient historical data access. External connections are defined through abstract methods that subclasses must implement for specific device types. The replication system leverages Hypercore's peer-to-peer protocol with replica discovery, enabling automatic master-slave synchronization where masters have full read/write capabilities while slaves operate in read-only mode. The Hook System provides extension points for subclasses to customize thing lifecycle operations.\n\n### Object Model\n\nThe following is a fragment of [MiningOS object model](https://docs.mos.tether.io/) that contains the abstract class representing \"thing\" (highlighted in blue). The rounded nodes reprsent abstract classes and the one square node represents a concrete class:\n\n```mermaid\n---\ntitle: Object Model of MiningOS\n---\nflowchart BT\n    bfx-wrk-base@{ shape: stadium, label: \"*bfx-wrk-base*\" }\n\n    tether-wrk-base@{ shape: stadium, label: \"*tether-wrk-base*\" }\n    tether-wrk-base---\u003ebfx-wrk-base\n\n    miningos-tlp-wrk-thing@{ shape: stadium, label: \"*miningos-tlp-wrk-thing*\" }\n    miningos-tlp-wrk-thing---\u003etether-wrk-base\n\n\n    miningos-tlp-wrk-electricity@{ shape: stadium, label: \"*miningos-tlp-wrk-electricity*\" }\n    miningos-tlp-wrk-electricity---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-switchgear@{ shape: stadium, label: \"*miningos-tlp-wrk-switchgear*\" }\n    miningos-tlp-wrk-switchgear---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-miner@{ shape: stadium, label: \"*miningos-tlp-wrk-miner*\" }\n    miningos-tlp-wrk-miner---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-container@{ shape: stadium, label: \"*miningos-tlp-wrk-container*\" }\n    miningos-tlp-wrk-container---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-powermeter@{ shape: stadium, label: \"*miningos-tlp-wrk-powermeter*\" }\n    miningos-tlp-wrk-powermeter---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-sensor@{ shape: stadium, label: \"*miningos-tlp-wrk-sensor*\" }\n    miningos-tlp-wrk-sensor---\u003eminingos-tlp-wrk-thing\n\n    miningos-tlp-wrk-minerpool@{ shape: stadium, label: \"*miningos-tlp-wrk-minerpool*\" }\n    miningos-tlp-wrk-minerpool---\u003eminingos-tlp-wrk-thing\n\n    miningos-wrk-ext-mempool[\"miningos-wrk-ext-mempool\"]\n    miningos-wrk-ext-mempool---\u003eminingos-tlp-wrk-thing\n\n    style miningos-tlp-wrk-thing fill:#005,stroke-width:4px\n```\n\n### Worker Types\nThe system implements a sophisticated multi-level inheritance hierarchy:\n\n#### Inheritance Levels\n```\nLevel 1: bfx-wrk-base (Foundation)\n    ↓\nLevel 2: tether-wrk-base (Foundation)\n    ↓\nLevel 3: miningos-tlp-wrk-thing/WrkProcVar (Thing Management Base)\n    ↓\nLevel 4: Device Category Templates\n    ↓\nLevel 5: Brand/Model Specific Implementations\n```\n\n#### Implementation Pattern\nEach level provides increasing specialization:\n- **Level 1**: Provides worker infrastructure (lifecycle, facilities, configuration)\n- **Level 2**: Provides worker infrastructure (lifecycle, facilities, configuration)\n- **Level 3**: Defines abstract methods like `connectThing()`, `collectThingSnap()`\n- **Level 4**: May provide default implementations or remain abstract\n- **Level 5**: Implements device-specific logic\n\nMiningOS implements a hierarchical class structure for different worker types:\n\n#### Level 1: Foundation\n- **bfx-wrk-base**: Core worker functionality (configuration, facilities, lifecycle)\n\n#### Level 2: Foundation \n- **tether-wrk-base**: Core worker functionality (configuration, facilities, lifecycle)\n\n#### Level 3: Thing Management Base\n- **miningos-tlp-wrk-thing (WrkProcVar)**: Abstract base implementing:\n  - Thing CRUD operations\n  - RPC interface\n  - Storage management\n  - Replication logic\n  - Abstract methods for device interaction\n\n#### Level 4: Device Category Templates\nThese templates extend the base thing class for specific device categories, providing:\n- Default implementations for common operations\n- Category-specific facilities\n- Shared business logic\n\nAvailable templates:\n- **miningos-tlp-wrk-container**: Container/rack infrastructure\n- **miningos-tlp-wrk-miner**: Mining hardware management\n- **miningos-tlp-wrk-powermeter**: Power monitoring equipment\n- **miningos-tlp-wrk-sensor**: Environmental and operational sensors\n- **miningos-tlp-wrk-switchgear**: Switchgear equipment\n\nThis architecture allows maximum code reuse while supporting diverse hardware with minimal implementation effort.\n\n## Core Concepts\n\n### Things\n\nA \"thing\" represents any manageable entity in MiningOS. While originally designed for physical devices, the concept has evolved to include any resource that requires monitoring, management, or data collection.\n\n### Snapshots\n\nPeriodic data collection from devices:\n\n- Device metrics --- hashrate, temperature, power according to each device type;\n- Operational status --- offline status is flagged by Thing class;\n- Errors (timeouts, connection failures, device errors);\n\n## API Reference\n\n### Thing Management\n\n#### Register Thing\n```javascript\nregisterThing(req)\n```\nCreates a new device in the system.\n\n**Parameters:**\n- `req.id`: Device ID (auto-generated if not provided)\n- `req.code`: Device code (auto-generated if not provided)\n- `req.opts`: Device options (**necessary** for connecting to device)\n- `req.info`: Device metadata (defaults to `{}` if not provided)\n- `req.tags`: Additional tags (auto-generated if not provided)\n- `req.comment`: Registration comment (optional)\n- `req.user`: User making the request (only used with comment)\n\n**Returns:** `1` on success\n\n**Errors:**\n- `ERR_SLAVE_BLOCK`: Operation blocked on slave nodes\n- `ERR_THING_WITH_ID_ALREADY_EXISTS`: Duplicate ID\n- `ERR_THING_WITH_CODE_ALREADY_EXISTS`: Duplicate code\n- `ERR_THING_CODE_INVALID`: Malformed string for code\n\n#### Update Thing\n```javascript\nupdateThing(req)\n```\nUpdates an existing device.\n\n**Parameters:**\n- `req.id` (the only required): Device ID\n- `req.opts`: Updated options\n- `req.info`: Updated metadata\n- `req.tags`: Updated tags\n- `req.forceOverwrite`: (boolean) Replace instead of merge (with *spread operator*)\n- `req.comment`: Update comment\n- `req.user`: User making the request\n- `req.actionId`: Action identifier for tracking\n\n**Returns:** `1` on success\n\n**Errors:**\n- `ERR_THING_NOTFOUND`: Device not found\n- `ERR_SLAVE_BLOCK`: Operation blocked on slave nodes\n\n#### List Things\n```javascript\nlistThings(req)\n```\nQuery devices with filters and pagination.\n\n**Parameters:** (all optional)\n- `req.query`: MongoDB-style query\n- `req.fields`: Field projection\n- `req.sort`: Sort criteria. None = maintains natural order\n- `req.offset`: Skip records (default: 0)\n- `req.limit`: Max records (default: 100)\n- `req.status`: Include status information\n\n**Returns:** Array of device objects\n\n**Errors:**\n- Implicitly through invalid MongoDB querries.\n\n#### Forget Things\n```javascript\nforgetThings(req)\n```\nRemove devices from the system.\n\n**Parameters:**\n- `req.query`: Query to select devices\n- `req.all`: (boolean) True means *'Remove all devices'*\n\n**Returns:** Number of devices removed\n\n**Errors:**\n- `ERR_SLAVE_BLOCK`: Operation blocked on slave nodes\n- Implicitly through invalid MongoDB querries.\n\n### Data Access\n\n#### Tail Log\n```javascript\ntailLog(req)\n```\nRetrieve time-series log data.\n\n**Parameters:**\n- `req.key`: Log type identifier\n- `req.tag`: Device tag\n- `req.offset`: Log file offset\n- `req.limit`: Max entries\n- `req.start`: Start timestamp\n- `req.end`: End timestamp\n- `req.fields`: Field projection\n\n**Returns:** Array of log entries\n\n#### Get Historical Logs\n```javascript\ngetHistoricalLogs(req)\n```\nRetrieve historical alerts or info changes.\n\n**Parameters:**\n- `req.logType`: 'alerts' or 'info'\n- `req.offset`: Starting offset\n- `req.limit`: Max entries\n- `req.start`: Start timestamp\n- `req.end`: End timestamp\n\n**Returns:** Array of historical entries\n\n### Thing Operations\n\n#### Query Thing\n```javascript\nqueryThing(req)\n```\nExecute a method on a specific device.\n\n**Parameters:**\n- `req.id`: Device ID\n- `req.method`: Method name\n- `req.params`: Method parameters\n\n**Returns:** Method execution result\n\n**Errors:**\n- `ERR_THING_NOTFOUND`: Device not found\n- `ERR_THING_NOT_INITIALIZED`: Device controller not ready\n- `ERR_THING_METHOD_NOTFOUND`: Method doesn't exist\n\n#### Apply Things\n```javascript\napplyThings(req)\n```\nExecute bulk operations on multiple devices.\n\n**Parameters:**\n- `req.method` (required): Method to execute\n- `req.query`: MongoDB-style query to select devices (default: all devices)\n- `req.params`: Array of parameters to pass to the method (default: empty)\n- `req.fields`: Field projection for device selection\n- `req.sort`: Sort criteria for device selection\n- `req.offset`: Number of devices to skip\n- `req.limit`: Maximum number of devices to process\n\n**Returns:** Number of successful operations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fminingos-tpl-wrk-thing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetherto%2Fminingos-tpl-wrk-thing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fminingos-tpl-wrk-thing/lists"}