block / block/proto-fleet

🤖 Refactor fleetnode runtime into shared execution path

Open
#725 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
55
Forks
16
Avg merge
1d 22h
Merged PRs (30d)
87

Description

🤖 Created by my AI agent.

## Problem

Fleet node support is growing a second implementation path for behavior the server already performs in combined/local deployments: plugin loading, discovery, pairing, telemetry reads, miner commands, artifact transfer, and node-local credential handling. This makes feature work land twice, increases drift risk between cloud-mode and combined-mode behavior, and makes RFC 0001 Phase 5 harder to reason about.

## Proposal

Treat `fleetd` combined/local mode as an embedded fleet node runtime rather than a separate server-side implementation.

Split responsibilities as:

- Server owns authorization, DB state, queues, audit, UI/API, scheduling, and policy decisions.
- Fleet node runtime owns miner I/O: plugin loading, discovery, pairing, telemetry reads, miner commands, artifact transfer, and node-local credentials.
- Transport decides where execution happens:
- `InProcessTransport` for combined/local server mode.
- `ControlStreamTransport` for remote fleet nodes.

The server should dispatch the same internal command model (`AgentCommand -> runtime executor -> result`) regardless of whether the target device is local or remote. Avoid making the server literally open a `ControlStream` to itself; use the same command envelope and executor, but call it in-process for combined mode.

## Suggested migration path

1. Extract shared runtime code from `server/cmd/fleetnode` into an internal package, likely `server/internal/fleetnode/runtime` or `server/internal/node/runtime`.
2. Move node-side execution for miner commands, discovery, pairing, telemetry, credential codec, and artifact helpers behind a small runtime interface.
3. Update `fleetnode run` to become a gateway adapter around that runtime.
4. Add an in-process runtime transport for `fleetd` combined/local mode.
5. Route server command execution through the same `AgentCommand` path for local and remote devices.
6. Delete direct server plugin-command branches once behavior parity is covered by tests.

Likely source areas to start from:

- `server/cmd/fleetnode/minercommand.go`
- `server/cmd/fleetnode/pair.go`
- `server/cmd/fleetnode/telemetry.go`
- `server/cmd/fleetnode/credential.go`
- `server/internal/domain/miner/remotenode/`
- `server/internal/domain/command/`
- `server/internal/domain/plugins/`

## Acceptance criteria

- Combined mode and remote fleet-node mode use the same miner-command executor for reboot/start/stop/curtail/power target/pool updates/password updates/log download/firmware update/telemetry reads where applicable.
- Discovery and pairing have one shared runtime implementation with transport-specific adapters only at the boundary.
- Server-side authorization, persistence, queueing, and audit remain server-owned and are not moved into the runtime.
- Tests cover parity between in-process and remote transports for representative command, pairing, and telemetry flows.
- The old duplicate server plugin-command path is removed or reduced to adapter glue.

## Notes / risks

- Keep transport separate from execution. Sharing the executor is the goal; forcing local execution through HTTP/2/ControlStream would add unnecessary failure modes.
- The runtime should not gain direct DB ownership. It should receive explicit command inputs and return typed results.
- This is a good precursor to the RFC 0001 internal package split and will make local UI/offline work easier to add later.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing execution paths in server/cmd/fleetnode/minercommand.go, pair.go, telemetry.go, and credential.go, then inspect server/internal/domain/miner/remotenode/, command/, and plugins/. Compare combined-mode and remote-node handling before defining the shared runtime boundary. Done means representative command, pairing, and telemetry parity tests pass while authorization, persistence, queueing, and audit remain server-owned.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend, distributed-systems
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.