Gateway plugins

Overview

The Gateway exposes HTTP routes through a declarative plugin system. Each plugin is a directory containing an mdk-plugin.json manifest and one or more controller files. MDK ships a set of default plugins that load automatically; you can mount additional plugins for your own site logic.

Prerequisites

• The Gateway is running
• A Kernel instance running and reachable, or kernelKey: false to start without a Kernel connection (development only)

Default plugins

MDK ships plugins that load automatically on Gateway startup:

• The telemetry plugin serves site metrics (hashrate, consumption, efficiency, temperature, and more)
• The site-hashrate plugin serves aggregated site hashrate history
• The site-monitor plugin serves site configuration, feature flags, and live per-device hashrate

The plugin reference lists every route each of these plugins serves, with its method, generated from the plugin's mdk-plugin.json. Plugins you mount yourself are documented by their own manifests.

const { startGateway } = require('@tetherto/mdk/backend/core/mdk')

await startGateway({
  kernel,
  port: 3000,
  extraPluginDirs: [
    path.join(__dirname, 'plugins/custom-metrics'),
    path.join(__dirname, 'plugins/alerts')
  ]
})

// controllers/live.js — read live telemetry
const mdkClient = require('../lib/client')

module.exports = async function live (req) {
  const deviceId = req.query.deviceId
  const telemetry = await mdkClient.pullTelemetry(deviceId, 'metrics')
  return { deviceId, ...telemetry }
}

// controllers/command.js — dispatch a command
const mdkClient = require('../lib/client')

module.exports = async function command (req) {
  const deviceId = req.params.deviceId
  const { mode } = req.body

  const result = await mdkClient.sendCommand(deviceId, 'setPowerMode', { mode })

  return {
    deviceId,
    commandId: result.commandId,
    status: result.status
  }
}

The req object

A controller's only argument. The controller reference documents every field (params, query, body, headers, _info) and how it's assembled.

The plugin's context module

require('@tetherto/mdk-gateway/plugin') resolves, inside a loaded plugin, to that plugin's own frozen context. The controller reference shows a controller building its own client from it:

Supplying per-plugin config

That per-plugin config isn't declared in mdk-plugin.json — it comes from the stack spec (spec.gateway.plugins[].config), passed as a config key alongside dir in the extraPluginDirs entry:

extraPluginDirs: [
  { dir: path.join(__dirname, 'plugins/custom-metrics'), config: { apiKey: process.env.METRICS_API_KEY } }
]

Build a lib/client.js from it once per plugin and require that module from every controller that needs one — there is no per-request Kernel access to guard, only the client's own connect failures:

try {
  return await mdkClient.pullTelemetry(deviceId, 'metrics')
} catch (err) {
  if (err.message === 'ERR_MDK_CLIENT_UNAVAILABLE') throw new Error('ERR_KERNEL_UNREACHABLE')
  throw err
}

Read hardware data

Call the client directly for live device data — pullTelemetry, getCapabilities, and listWorkers are documented with their return shapes in the client's own reference.

A Worker is single-device, so a live fleet-wide total — hashrate across every miner on site, say — is the controller's own job: list every Worker, pull each device's live telemetry, and add the numbers up:

const { workers } = await mdkClient.listWorkers()
const pulls = workers.flatMap((w) => (w.deviceIds || []).map(async (deviceId) => {
  const { metrics } = await mdkClient.pullTelemetry(deviceId, 'metrics')
  return metrics?.stats?.hashrate_mhs?.avg || 0
}))
const totalHashrateMhs = (await Promise.all(pulls)).reduce((sum, v) => sum + v, 0)

site-monitor/controllers/hashrate.js is the shipping example this pattern is copied from.

There is no separate Gateway-side store for historical or aggregated data, either. Fan pullWorkerTelemetry out across every registered Worker and read the series from the Worker's own persisted tail-log:

const { workers } = await mdkClient.listWorkers()
const results = await Promise.allSettled(
  workers.map((w) => mdkClient.pullWorkerTelemetry(w.workerId, { type: 'logs', key: 'stat-1D', tag: 't-miner', start, end }))
)

The default telemetry controllers and telemetry/lib/site-data.js show a worked, production version of this fan-out (aliasing, error tolerance per Worker, and the aggregation shapes each route returns).

Send a command

sendCommand dispatches via the Kernel to the Worker that owns the device — the command must be declared in the Worker's mdk-contract.json. controllers/command.js above already shows the pattern; the client's own reference documents the full return shape (commandId, status, result, error).

Caching

Add a "cache" array of dot-path strings to a route to enable request-level caching, bypassed with ?overwriteCache=true. The manifest reference shows the field in a real manifest.

Stream routes

Add "stream": true to a route to own the raw ServerResponse instead of returning a plain value — for SSE or any other response Fastify shouldn't serialize. The manifest reference covers the mechanism and the handler's error behavior. backend/plugins/agent is a shipping example — its message route streams text/event-stream this way; see the agent Gateway-deployment guide for the consumer side.

Auth and permissions

The Gateway applies no authentication of its own, as its authentication design describes. Every route a plugin declares is served to any caller, so a route that needs protecting carries that logic in its own controller. Identity is yours to supply: the manifest "auth" and "permissions" fields have no reader and change nothing. The bundled auth plugin is not a substitute — the Gateway neither registers it nor gives its controllers what they still expect.

Validate the token with your own identity layer and check it in the handler:

const { validateToken } = require('../lib/my-identity-layer')

module.exports = async function protectedRoute (req) {
  const token = req.headers.authorization?.replace('Bearer ', '')
  if (!token) throw new Error('ERR_UNAUTHORIZED')

  const { permissions } = validateToken(token)
  if (!permissions.includes('miner:w')) throw new Error('ERR_FORBIDDEN')

  // Your route logic
}

Manifest validation errors

The plugin loader validates every manifest and handler at startup and throws if anything is wrong — see the loader's error codes for the full list.

Next steps

• Try the live site backend example for a complete worked plugin with three routes: a live site overview, a historical series, and a command endpoint running under PM2 or Docker
• Build the minimal dashboard tutorial — end-to-end worked example of the single-plugin + controller pattern
• Understand how Workers declare their data via mdk-contract.json — what mdkClient reads and sendCommand dispatches
• See the full manifest and controller reference
• Review the Gateway API and config