diff --git a/internal/mirror/client.go b/internal/mirror/client.go new file mode 100644 index 0000000..d2c830b --- /dev/null +++ b/internal/mirror/client.go @@ -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 +} diff --git a/internal/mirror/client_test.go b/internal/mirror/client_test.go new file mode 100644 index 0000000..8c0c750 --- /dev/null +++ b/internal/mirror/client_test.go @@ -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") + } +}