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.

Default plugins

MDK ships plugins that load automatically on Gateway startup:

• The auth plugin serves identity and token endpoints under /auth
• The telemetry plugin serves site metrics (hashrate, consumption, efficiency, temperature, and more) under /auth/metrics
• The site-hashrate plugin serves aggregated site hashrate history

The plugin reference lists every default route, its method, and whether it needs a token — those tables are generated from each plugin's mdk-plugin.json. Plugins you mount yourself are documented by their own manifests.

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

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

// controllers/live.js — read live telemetry
module.exports = async function live (req, services) {
  const deviceId = req.query.deviceId
  const telemetry = await services.mdkClient.pullTelemetry(deviceId, 'metrics')
  return { deviceId, ...telemetry }
}

// controllers/command.js — dispatch a command
module.exports = async function command (req, services) {
  const deviceId = req.params.deviceId
  const { mode } = req.body

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

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

The req object

The services object

if (!services.mdkClient) throw new Error('ERR_MDK_CLIENT_UNAVAILABLE')

if (!services.authLib) throw new Error('ERR_AUTH_LIB_UNAVAILABLE')

Read hardware data

For live device data use mdkClient:

// Pull a live metrics snapshot
const tel = await services.mdkClient.pullTelemetry(deviceId, 'metrics')

// Pull the declared capabilities (from the Worker's mdk-contract.json)
const { capabilities } = await services.mdkClient.getCapabilities(deviceId)

// List all registered Workers
const { workers } = await services.mdkClient.listWorkers()

For historical or aggregated series from a Worker's persisted tail-log use dataProxy:

const results = await services.dataProxy.requestData('tailLogRangeAggr', {
  type: 'miner',
  startDate: start,
  endDate: end,
  fields: { hashrate_sum: 1 }
})

The default telemetry controllers show worked examples of both patterns.

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. It returns:

const result = await services.mdkClient.sendCommand(deviceId, 'reboot', {})
if (result.status === 'FAILED') throw new Error(result.error)
return { commandId: result.commandId, status: result.status }

Auth, permissions, and caching

Auth — set "auth": true on a route to require a valid Bearer token. The adapter runs authCheck before the handler is called.

Permissions — add a "permissions" array to enforce RBAC:

{
  "id": "site.miners.command",
  "auth": true,
  "permissions": ["actions:w"],
  "handler": "./controllers/command.js",
  "http": { "method": "POST", "path": "/site/miners/{deviceId}/command" }
}

Caching — add a "cache" array of dot-path strings to enable request-level caching. The cache key is composed from the route ID and the resolved values of each path:

{
  "id": "telemetry.hashrate",
  "cache": ["query.start", "query.end", "query.groupBy"],
  ...
}

Pass ?overwriteCache=true to any cached route to bypass and refresh.

Manifest validation errors

The plugin loader validates every manifest and handler at startup and throws if anything is wrong:

Troubleshooting

// Before (v0.2 — no longer works)
const server = require('@tetherto/mdk-gateway/workers/lib/server')
server.metricsRoutes.push(myCustomRoute)

// After (v0.3+)
await startGateway({
  kernel,
  extraPluginDirs: [path.join(__dirname, 'plugins/my-metrics')]
})

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 services reference
• Review the Gateway API and config