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. A Gateway loads exactly the plugins your stack declares in spec.gateway.plugins[] and nothing else, whether they are yours or ones MDK ships.

Prerequisites

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

Plugins MDK ships

The supported plugins reference is the source of truth for what currently ships and the routes each serves. The site plugins it bundles today are subpaths of the @tetherto/mdk-plugins package, so each is named by its subpath:

# mdk.yaml
spec:
  gateway:
    port: 3847
    plugins:
      - package: "@tetherto/mdk-plugins/telemetry"
      - package: "@tetherto/mdk-plugins/site-monitor"

Plugins you mount yourself are documented by their own manifests.

const { startGateway, bundledPluginDir } = require('@tetherto/mdk-core')

await startGateway({
  kernel,
  port: 3000,
  extraPluginDirs: [
    path.join(__dirname, 'plugins/custom-metrics'),
    path.join(__dirname, 'plugins/alerts'),
    bundledPluginDir('telemetry')      // one MDK ships, by name rather than by path
  ]
})

// 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)

demo/controllers/summary.js is the smallest worked example of this fan-out, worth starting from if you're authoring your own plugin.

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 }))
)

demo/controllers/history.js is the smallest worked example — a single-file version with an optional per-device filter and a Kernel-unavailable fallback.

Both live and historical calls are network calls through the client — guard both the same way. An unguarded pullTelemetry or pullWorkerTelemetry throws ERR_MDK_CLIENT_UNAVAILABLE straight through to the caller as an unhandled 500 the moment a Worker or the Kernel drops; neither path degrades more gracefully than the other.

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 shows the pattern; return shape is 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 Object.assign(new Error('ERR_UNAUTHORIZED'), { statusCode: 401 })

  const { permissions, email } = validateToken(token)
  if (!permissions.includes('miner:w')) throw Object.assign(new Error('ERR_FORBIDDEN'), { statusCode: 403 })

  // Pass email and permissions into Kernel yourself. Do not take them from req.body.
}

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
• Read the demo plugin for the smallest complete worked example of both fan-out patterns above
• 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