Let the control plane call the mirror instead of somebody SSHing to it

The mirror has had a management API since it was built, and the only thing
driving it was curl on the mirror's own machine. This is the other half: a
client, so the operations belong to whatever has a reason to perform them.

The mirror's refusals travel as their own sentence rather than a status code.
Putting the reason in the body was deliberate on the server side, and a client
that kept only the number would undo it — "the mirror said 400" sends somebody
to the wrong machine, "the source URL answered 404" sends them to the right one.

NextProtos is cleared for the same reason the mirror's server clears it. That
configuration is shaped for the agent stream, which pins h2; a transport
carrying a pinned protocol it is not set up to speak negotiates h2 and then
talks HTTP/1.1 over it, and fails with an error mentioning neither ALPN nor
the mirror.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5 committed 2026-09-27 10:16:54 +02:00
1 parent afb3797e57
commit 7e6fb0059a
2 files changed
+317

No files matched your search

+169
View File
@@ -0,0 +1,169 @@
package mirror
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
)
// Client drives a mirror's management API from somewhere else.
//
// The mirror runs on its own machine with its own disk, so every operation the
// control plane wants — what is held, fetch this, how far along, remove that —
// is a request over the network rather than a function call. This is the half
// that makes the mirror something the control plane administers instead of
// something an operator has to SSH into.
type Client struct {
base string
hc *http.Client
}
// NewClient dials a mirror's management API, with mutual TLS when configured.
//
// NextProtos is cleared from what tlsconf builds, for the same reason the
// mirror's server clears it: that configuration is shaped for the agent stream,
// which needs HTTP/2 and pins "h2". A transport carrying a TLS config with a
// pinned protocol it is not itself set up to speak negotiates h2 and then talks
// HTTP/1.1 over it, which fails as a protocol error that mentions neither ALPN
// nor the mirror. Cleared here and ForceAttemptHTTP2 set, net/http negotiates
// whichever the two ends agree on and speaks it.
func NewClient(addr string, tc tlsconf.Config, timeout time.Duration) (*Client, error) {
u, err := url.Parse(addr)
if err != nil || u.Host == "" {
return nil, fmt.Errorf("the mirror address %q is not a URL with a host", addr)
}
if timeout <= 0 {
timeout = 15 * time.Second
}
hc := &http.Client{Timeout: timeout}
if tc.Enabled() {
cfg, err := tc.ClientConfig(u.Hostname())
if err != nil {
return nil, fmt.Errorf("the mirror's TLS configuration: %w", err)
}
cfg.NextProtos = nil
hc.Transport = &http.Transport{TLSClientConfig: cfg, ForceAttemptHTTP2: true}
}
return &Client{base: strings.TrimSuffix(addr, "/"), hc: hc}, nil
}
// Addr is where this client points, for a page that has to say so.
func (c *Client) Addr() string { return c.base }
// APIError is a refusal the mirror explained.
//
// The status and the mirror's own sentence, both: a page showing "the mirror
// said 400" sends somebody to the wrong machine, while "the source URL returned
// 404" sends them to the right one. The status is kept alongside so a caller
// can still branch on it without parsing prose.
type APIError struct {
Status int
Msg string
}
func (e *APIError) Error() string {
if e.Msg == "" {
return fmt.Sprintf("the mirror answered %d", e.Status)
}
return e.Msg
}
// Health reports whether the mirror is up and can read its own directory.
func (c *Client) Health(ctx context.Context) error {
var out map[string]any
return c.do(ctx, http.MethodGet, "/v1/health", nil, &out)
}
// List is everything the mirror holds or is fetching.
func (c *Client) List(ctx context.Context) (ModelsResponse, error) {
var out ModelsResponse
err := c.do(ctx, http.MethodGet, "/v1/models", nil, &out)
return out, err
}
// Fetch asks the mirror to download a model.
//
// It returns as soon as the download is under way, not when it finishes —
// that is the mirror's contract and it is the caller's too. Poll Status.
func (c *Client) Fetch(ctx context.Context, req FetchRequest) (FetchResponse, error) {
var out FetchResponse
err := c.do(ctx, http.MethodPost, "/v1/models", req, &out)
return out, err
}
// Status is where one model version stands.
func (c *Client) Status(ctx context.Context, model, version string) (FetchResponse, error) {
var out FetchResponse
err := c.do(ctx, http.MethodGet,
"/v1/models/"+url.PathEscape(model)+"/"+url.PathEscape(version), nil, &out)
return out, err
}
// Remove deletes a whole version and reports the files that went.
func (c *Client) Remove(ctx context.Context, model, version string) ([]string, error) {
var out struct {
Removed []string `json:"removed"`
}
err := c.do(ctx, http.MethodDelete,
"/v1/models/"+url.PathEscape(model)+"/"+url.PathEscape(version), nil, &out)
return out.Removed, err
}
func (c *Client) do(ctx context.Context, method, path string, body, out any) error {
var rdr io.Reader
if body != nil {
b, err := json.Marshal(body)
if err != nil {
return err
}
rdr = bytes.NewReader(b)
}
req, err := http.NewRequestWithContext(ctx, method, c.base+path, rdr)
if err != nil {
return err
}
if body != nil {
req.Header.Set("Content-Type", "application/json")
}
resp, err := c.hc.Do(req)
if err != nil {
// Wrapped with the address because the failure an operator sees on a
// page is otherwise "connection refused" with no clue which of the two
// machines refused it.
return fmt.Errorf("reaching the mirror at %s: %w", c.base, err)
}
defer resp.Body.Close()
// Capped: the mirror is trusted but it is still a separate process over a
// network, and a page that renders whatever it sends should not be able to
// be handed a gigabyte.
raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if err != nil {
return fmt.Errorf("reading the mirror's answer: %w", err)
}
if resp.StatusCode >= 300 {
var e struct {
Error string `json:"error"`
}
_ = json.Unmarshal(raw, &e)
return &APIError{Status: resp.StatusCode, Msg: e.Error}
}
if out == nil {
return nil
}
if err := json.Unmarshal(raw, out); err != nil {
return fmt.Errorf("the mirror's answer was not the JSON expected: %w", err)
}
return nil
}
+148
View File
@@ -0,0 +1,148 @@
package mirror
import (
"context"
"errors"
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
)
// testClient puts a real API behind a real HTTP server and points a real client
// at it, because the thing worth testing is the round trip: a handler and a
// client that each look right on their own can still disagree about a field
// name or a status code, and nothing but the two together catches that.
func testClient(t *testing.T) (*Client, string) {
t.Helper()
a, root := testAPI(t)
srv := httptest.NewServer(a.Handler())
t.Cleanup(srv.Close)
c, err := NewClient(srv.URL, tlsconf.Config{}, 0)
if err != nil {
t.Fatal(err)
}
return c, root
}
func TestTheClientReadsWhatTheMirrorHolds(t *testing.T) {
c, root := testClient(t)
writeFile(t, filepath.Join(root, "llama", "2026-01", "model.gguf"), "weights")
got, err := c.List(t.Context())
if err != nil {
t.Fatal(err)
}
// The base comes back from the mirror rather than being assembled here: the
// catalog entry has to be spelled the way the mirror spells it, and two
// spellings of one address is what makes a file in use look unused.
if got.Base != "http://mirror:8081" {
t.Errorf("expected the mirror's own base, got %q", got.Base)
}
if len(got.Models) != 1 || got.Models[0].Model != "llama" {
t.Fatalf("expected the one model on disk, got %+v", got.Models)
}
if got.Models[0].State != Present {
t.Errorf("expected present, got %q", got.Models[0].State)
}
}
func TestFetchReturnsBeforeTheDownloadFinishes(t *testing.T) {
c, _ := testClient(t)
got, err := c.Fetch(t.Context(), FetchRequest{
Source: serving(t, "weights"), Model: "m", Version: "v",
})
if err != nil {
t.Fatal(err)
}
// Under way, not done. A caller that waited for the bytes would hold a
// connection open for an hour on a real model and time out in between.
if got.Status.State != Fetching && got.Status.State != Present {
t.Errorf("expected the download to be under way, got %q", got.Status.State)
}
if got.URL != "http://mirror:8081/m/v/model.gguf" {
t.Errorf("the answer should say where the catalog will point; got %q", got.URL)
}
waitFor(t, "the download to finish", func() bool {
st, err := c.Status(t.Context(), "m", "v")
return err == nil && st.Status.State == Present
})
}
func TestTheMirrorsReasonSurvivesTheHop(t *testing.T) {
c, _ := testClient(t)
_, err := c.Fetch(t.Context(), FetchRequest{Source: "http://x/model.gguf"})
// The whole point of the mirror putting its reason in the body is that the
// far end can show it. A client that kept only the status code would turn
// "model and version are required" into "the mirror said 400".
var apiErr *APIError
if !errors.As(err, &apiErr) {
t.Fatalf("expected an APIError, got %v", err)
}
if apiErr.Status != http.StatusBadRequest {
t.Errorf("expected 400, got %d", apiErr.Status)
}
if !strings.Contains(apiErr.Error(), "version") {
t.Errorf("the reason should name what was missing; got %q", apiErr.Error())
}
}
func TestAnUnknownModelComesBackAsNotFound(t *testing.T) {
c, _ := testClient(t)
_, err := c.Status(t.Context(), "nope", "v1")
var apiErr *APIError
if !errors.As(err, &apiErr) || apiErr.Status != http.StatusNotFound {
t.Fatalf("expected a 404 APIError, got %v", err)
}
}
func TestRemoveReportsWhatWent(t *testing.T) {
c, root := testClient(t)
writeFile(t, filepath.Join(root, "m", "v", "part-1.safetensors"), "a")
writeFile(t, filepath.Join(root, "m", "v", "part-2.safetensors"), "b")
removed, err := c.Remove(t.Context(), "m", "v")
if err != nil {
t.Fatal(err)
}
if len(removed) != 2 {
t.Errorf("both files of the version should have gone; got %v", removed)
}
}
func TestHealthFailsWhenTheMirrorIsNotThere(t *testing.T) {
// A closed port, not a slow one: the page has to be able to say the mirror
// is unreachable rather than render an empty table that looks like a mirror
// holding nothing.
srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
addr := srv.URL
srv.Close()
c, err := NewClient(addr, tlsconf.Config{}, 0)
if err != nil {
t.Fatal(err)
}
if err := c.Health(context.Background()); err == nil {
t.Fatal("expected an error from a mirror that is not listening")
} else if !strings.Contains(err.Error(), addr) {
t.Errorf("the error should name the address that refused; got %q", err)
}
}
func TestAnAddressWithoutAHostIsRefusedAtConstruction(t *testing.T) {
// Caught here rather than at the first request: a typo in configuration
// should stop the control plane starting, not surface as a broken page
// hours later.
if _, err := NewClient("10.0.0.146:8082", tlsconf.Config{}, 0); err == nil {
t.Error("expected an address with no scheme to be refused")
}
}