DriverVault/API Server/internal/api/integrations_ankersolix_modbus.go

package api

// The local half of the Anker Solix control plane. Where the OCPP path in
// integrations_ankersolix_control.go waits for the charger to dial in to us,
// this one dials the charger: Modbus TCP on its own network, using the register
// map Anker publishes for the V1 (see the plugin's modbus.go). That inversion is
// the whole point — a charger behind a customer's router can be controlled this
// way without any inbound reachability, a public endpoint or a TLS certificate.
//
// The trade-off is that the server must share a network with the charger, so
// this mode is selectable per user rather than assumed.

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net"
	"net/http"
	"strings"
	"time"

	"drivervault/apiserver/internal/modbus"
	"drivervault/apiserver/internal/plugins/builtin/ankersolix"
)

// modbusActionTimeout bounds one dial-plus-exchange. The charger is on the LAN,
// so this is generous; it exists so an unreachable address fails the request
// rather than holding it open.
const modbusActionTimeout = 10 * time.Second

// ankerModbusConfig reads a charger's local address out of its stored binding.
func ankerModbusConfig(b ankerChargerBinding) ankersolix.ModbusConfig {
	return ankersolix.ModbusConfig{Host: strings.TrimSpace(b.ModbusHost), Port: b.ModbusPort}
}

// ankerModbusAction issues one control command over Modbus TCP. The gate,
// rate limit, destructive-action confirmation and audit have already run in
// handleAnkerControlAction; this decides what to write and reports the outcome.
func (s *Server) ankerModbusAction(w http.ResponseWriter, r *http.Request, who *callerIdentity,
	binding ankerChargerBinding, sn, action string, body ankerControlBody) {

	// Actions the register map has no equivalent for. Saying which transport is
	// missing them beats a bare "unknown action" the caller cannot act on.
	switch action {
	case "reset", "restart":
		// No register reboots the charger. Both of the other transports can, so
		// the refusal names them rather than only the CSMS.
		writeError(w, http.StatusBadRequest,
			"no register reboots the charger; the local Modbus connection cannot restart it. Switch the control mode to Anker cloud (MQTT) or a CSMS mode to use it.")
		return
	case "unlock", "availability", "trigger", "config":
		writeError(w, http.StatusBadRequest,
			"\""+action+"\" is an OCPP command; the local Modbus connection cannot send it. Switch the control mode to a CSMS mode to use it.")
		return
	case "settings":
		// The register map holds five control registers; the charger's own
		// configuration — schedules, switches, load balancing — is not among them.
		writeError(w, http.StatusBadRequest,
			"\"settings\" writes the charger's own configuration, which the register map does not expose. Switch the control mode to Anker cloud (MQTT) to use it.")
		return
	case "clear-limit":
		// The register takes an explicit ceiling and the charger clamps anything
		// above its rating, so "no limit" would mean writing a value we would have
		// to guess. Asking for the real one is better than guessing wrong.
		writeError(w, http.StatusBadRequest,
			"the local connection has no \"clear limit\" command; send \"limit\" with the amps you want instead")
		return
	}

	ctx, cancel := context.WithTimeout(r.Context(), modbusActionTimeout)
	defer cancel()

	client, err := ankersolix.ModbusDial(ctx, ankerModbusConfig(binding))
	if err != nil {
		s.auditControl(who, sn, action, nil, "error", err)
		writeJSON(w, http.StatusBadGateway, map[string]any{"error": err.Error()})
		return
	}
	defer client.Close()

	var (
		result any
		params = map[string]any{"transport": "modbus"}
	)
	switch action {
	case "start":
		err = ankersolix.ModbusStartCharging(ctx, client)
	case "stop":
		err = ankersolix.ModbusStopCharging(ctx, client)
	case "limit":
		params["amps"] = body.Amps
		err = ankersolix.ModbusSetMaxCurrent(ctx, client, body.Amps)
	case "boost":
		on := body.On == nil || *body.On
		params["on"] = on
		err = ankersolix.ModbusSetBoost(ctx, client, on)
	case "phase":
		if body.PhaseMode == nil {
			writeError(w, http.StatusBadRequest, "phase requires \"phase\": 0 (automatic), 1 (single) or 2 (three)")
			return
		}
		params["phase"] = *body.PhaseMode
		err = ankersolix.ModbusSetPhaseMode(ctx, client, *body.PhaseMode)
	case "timeout":
		params["seconds"] = body.Seconds
		err = ankersolix.ModbusSetTimeout(ctx, client, body.Seconds)
	case "status":
		var snap ankersolix.ModbusSnapshot
		snap, err = ankersolix.ModbusRead(ctx, client, true)
		result = snap
	default:
		writeError(w, http.StatusBadRequest, "unknown control action: "+action)
		return
	}

	outcome := "accepted"
	if err != nil {
		outcome = "error"
	}
	s.auditControl(who, sn, action, params, outcome, err)

	if err != nil {
		// A register the charger refused is a bad request, not a bad gateway: the
		// link worked and the charger said no.
		status := http.StatusBadGateway
		var mbErr *modbus.Error
		if errors.As(err, &mbErr) {
			status = http.StatusBadRequest
		}
		writeJSON(w, status, map[string]any{"error": err.Error()})
		return
	}

	resp := map[string]any{"status": outcome}
	if result != nil {
		resp["result"] = result
	}
	writeJSON(w, http.StatusOK, resp)
}

// handleAnkerControlAddress saves (or clears, on DELETE) the local address of one
// charger's Modbus TCP server — the address the Anker app shows once Modbus is
// enabled on the device.
func (s *Server) handleAnkerControlAddress(w http.ResponseWriter, r *http.Request) {
	who := caller(r)
	if who == nil {
		writeError(w, http.StatusUnauthorized, "not authenticated")
		return
	}
	if !s.pb.Configured() {
		writeError(w, http.StatusServiceUnavailable, "integration settings not configured on the server")
		return
	}
	sn := strings.TrimSpace(r.PathValue("sn"))
	if sn == "" {
		writeError(w, http.StatusBadRequest, "missing charger serial")
		return
	}

	var host string
	var port int
	if r.Method != http.MethodDelete {
		var body struct {
			Host string `json:"host"`
			Port int    `json:"port"`
		}
		if r.Body != nil {
			_ = json.NewDecoder(r.Body).Decode(&body)
		}
		host = strings.TrimSpace(body.Host)
		port = body.Port
		if err := validateModbusAddress(host, port); err != nil {
			writeError(w, http.StatusBadRequest, err.Error())
			return
		}
	}

	userRaw := s.userPluginSettings(r.Context(), who.ID)
	newDoc := mergeAnker(userRaw, func(as *ankerStored) {
		if as.ControlChargers == nil {
			as.ControlChargers = map[string]ankerChargerBinding{}
		}
		// Keep whatever else the binding holds: a charger may carry both an OCPP
		// token and a local address, and switching control mode must not discard
		// the other one.
		b := as.ControlChargers[sn]
		b.ModbusHost, b.ModbusPort = host, port
		if b.AddedAt == "" {
			b.AddedAt = time.Now().UTC().Format(time.RFC3339)
		}
		as.ControlChargers[sn] = b
	})
	if err := s.pb.Update(r.Context(), s.usersCollection(), who.ID,
		map[string]any{"pluginSettings": newDoc}, nil); err != nil {
		writePBError(w, err)
		return
	}

	action := "address.set"
	if host == "" {
		action = "address.clear"
	}
	s.auditControl(who, sn, action, map[string]any{"host": host, "port": port}, "ok", nil)
	writeJSON(w, http.StatusOK, map[string]any{"serial": sn, "modbusHost": host, "modbusPort": port})
}

// validateModbusAddress checks a user-supplied charger address. Loopback is
// refused because this address is one the server dials on the caller's behalf,
// and 127.0.0.1 would point it at services running on the server itself rather
// than at a charger. Other addresses are allowed: the charger is expected on a
// private LAN, but a routed or VPN deployment is legitimate too.
func validateModbusAddress(host string, port int) error {
	if host == "" {
		return errors.New("the charger's local address is required")
	}
	if port < 0 || port > 65535 {
		return fmt.Errorf("%d is not a valid port", port)
	}
	if strings.ContainsAny(host, " /\\?#@") {
		return errors.New("the address should be just a hostname or IP, with no scheme or path")
	}
	if ip := net.ParseIP(host); ip != nil {
		if ip.IsLoopback() || ip.IsUnspecified() {
			return errors.New("that address points at the server itself, not at a charger")
		}
	} else if strings.EqualFold(host, "localhost") {
		return errors.New("that address points at the server itself, not at a charger")
	}
	return nil
}

// ankerModbusSnapshot reads a charger's live state for the status endpoint. It
// is best effort: a charger that is switched off or on another network simply
// has no snapshot, which is not an error in a status report.
func (s *Server) ankerModbusSnapshot(ctx context.Context, binding ankerChargerBinding) (ankersolix.ModbusSnapshot, bool) {
	if strings.TrimSpace(binding.ModbusHost) == "" {
		return ankersolix.ModbusSnapshot{}, false
	}
	ctx, cancel := context.WithTimeout(ctx, modbusActionTimeout)
	defer cancel()

	client, err := ankersolix.ModbusDial(ctx, ankerModbusConfig(binding))
	if err != nil {
		return ankersolix.ModbusSnapshot{}, false
	}
	defer client.Close()

	snap, err := ankersolix.ModbusRead(ctx, client, true)
	if err != nil {
		return ankersolix.ModbusSnapshot{}, false
	}
	return snap, true
}