// Package fleetapi is the client half of the fleet store door (spec
// 2026-08-11-fleet-api-surface-design.md, F5; Task 2's server is
// internal/edge/storedoor.go). It implements release.Store over the five
// HTTPS operations the door serves on the edge's reserved tunnel hostname —
// GET/PUT/DELETE /store/o/<key>, GET /store/list, GET /store/dirs — using the
// same two headers a tunnel dial already carries: "Authorization: Bearer
// <token>" and "Carlos-Tunnel-Name: <fleet>/<label>". A box that builds one
// of these needs no AWS credentials on the platform's deployment bucket at
// all: every loop that already speaks release.Store — adoption, fast
// convergence, config, status, metrics, bindings — runs unchanged against it.
package fleetapi

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net"
	"net/http"
	"net/url"
	"os"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/release"
)

// callTimeout bounds connect, TLS handshake, and the wait for the response
// headers to start arriving — the "is the edge even alive and answering"
// phase of a call. It deliberately does NOT bound the rest of the exchange
// (reading/writing the body): Get is the artifact-download path (release
// adoption fetches whole app.tar.gz bodies through this store), and this
// spec's own target box class — home broadband, a Pi's uplink — can take
// well over 30s to pull a large artifact while still making steady
// progress. Putting this on http.Client.Timeout instead (a whole-exchange
// wall clock) would fail every such transfer deterministically, on every
// adoption pass, forever; S3Store has no equivalent cap, so this store must
// not invent a stricter one. A wedged edge that never starts answering still
// fails fast — that's what ResponseHeaderTimeout below is for.
const callTimeout = 30 * time.Second

// store is the client half of the door: release.Store spoken over base's
// /store/ routes, authenticated by name/token on every request.
type store struct {
	base   string // origin, no trailing slash — e.g. "https://tunnel.example.com"
	name   string // Carlos-Tunnel-Name: "<fleet>/<label>"
	token  string // bearer token; NEVER placed in an error string (see errorf)
	client *http.Client
}

// New builds a release.Store speaking the edge's store door at base
// (CARLOS_TUNNEL_URL's origin) as the fleet channel identity name/token (the
// box's CARLOS_TUNNEL_NAME/_TOKEN). All three are required — there is no
// meaningful partial identity to fall back to, and a caller that got one of
// them empty has a config bug worth failing on at construction rather than
// on the first call.
func New(base, name, token string) (release.Store, error) {
	if base == "" {
		return nil, errors.New("fleetapi: base is required")
	}
	if name == "" {
		return nil, errors.New("fleetapi: name is required")
	}
	if token == "" {
		return nil, errors.New("fleetapi: token is required")
	}
	u, err := url.Parse(base)
	if err != nil || u.Scheme == "" || u.Host == "" {
		return nil, fmt.Errorf("fleetapi: invalid base %q: want an absolute URL", base)
	}
	return &store{
		base:  strings.TrimSuffix(base, "/"),
		name:  name,
		token: token,
		// No Client.Timeout (see callTimeout's comment): only the connect/TLS/
		// response-header phase is bounded, so a slow-but-progressing artifact
		// transfer can still finish.
		client: &http.Client{Transport: &http.Transport{
			Proxy: http.ProxyFromEnvironment,
			DialContext: (&net.Dialer{
				Timeout:   callTimeout,
				KeepAlive: 30 * time.Second,
			}).DialContext,
			TLSHandshakeTimeout:   callTimeout,
			ResponseHeaderTimeout: callTimeout,
			ExpectContinueTimeout: 1 * time.Second,
		}},
	}, nil
}

// errorf builds a client-side error. Every call site here formats around
// the key/prefix and the response shape only — never s.token — so a leaked
// error string (a log line, a status page) can never hand back the bearer
// credential this store authenticates with.
func errorf(format string, args ...any) error {
	return fmt.Errorf("fleetapi: "+format, args...)
}

// objectURL builds the /store/o/<key> URL, percent-encoding key the same way
// any other path segment is encoded — the door decodes it back with
// net/http's ordinary request parsing (storedoor.go's canonicalKey comment:
// "already percent-decoded by net/http"), so this is the inverse of that,
// not a second canonicalization.
func (s *store) objectURL(key string) string {
	u := url.URL{Path: "/store/o/" + key}
	return s.base + u.EscapedPath()
}

func (s *store) listURL(path, prefix string) string {
	return s.base + path + "?" + url.Values{"prefix": {prefix}}.Encode()
}

// newRequest attaches the two headers every door route requires (F1): the
// same bearer token and channel name a tunnel dial sends.
func (s *store) newRequest(ctx context.Context, method, rawURL string, body io.Reader) (*http.Request, error) {
	req, err := http.NewRequestWithContext(ctx, method, rawURL, body)
	if err != nil {
		return nil, errorf("build request: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+s.token)
	req.Header.Set("Carlos-Tunnel-Name", s.name)
	return req, nil
}

// Get fetches key and its etag. A 404 — which the door hands back
// byte-identically whether the key never existed, belongs to another
// tenant, or the caller's credential is bad (spec: no response distinguishes
// them) — is mapped uniformly onto release.Store's os.ErrNotExist contract:
// this client cannot tell those apart either, by design, and must not
// pretend otherwise.
func (s *store) Get(ctx context.Context, key string) ([]byte, string, error) {
	req, err := s.newRequest(ctx, http.MethodGet, s.objectURL(key), nil)
	if err != nil {
		return nil, "", err
	}
	resp, err := s.client.Do(req)
	if err != nil {
		return nil, "", errorf("get %s: %w", key, err)
	}
	defer resp.Body.Close()
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, "", errorf("get %s: read body: %w", key, err)
	}
	switch resp.StatusCode {
	case http.StatusOK:
		return body, resp.Header.Get("ETag"), nil
	case http.StatusNotFound:
		return nil, "", fmt.Errorf("fleetapi: %s: %w", key, os.ErrNotExist)
	default:
		return nil, "", errorf("get %s: unexpected status %d", key, resp.StatusCode)
	}
}

// Open streams one object. Unlike Get it does not buffer the body, which
// is what a 25 MiB platform binary on a Pi needs; the 404 mapping is the
// same as Get's so callers can errors.Is(err, os.ErrNotExist).
func (s *store) Open(ctx context.Context, key string) (io.ReadCloser, string, error) {
	req, err := s.newRequest(ctx, http.MethodGet, s.objectURL(key), nil)
	if err != nil {
		return nil, "", err
	}
	resp, err := s.client.Do(req)
	if err != nil {
		return nil, "", errorf("open %s: %w", key, err)
	}
	switch resp.StatusCode {
	case http.StatusOK:
		return resp.Body, resp.Header.Get("ETag"), nil
	case http.StatusNotFound:
		resp.Body.Close()
		return nil, "", fmt.Errorf("fleetapi: %s: %w", key, os.ErrNotExist)
	default:
		resp.Body.Close()
		return nil, "", errorf("open %s: unexpected status %d", key, resp.StatusCode)
	}
}

var _ release.Opener = (*store)(nil)

// No release.PutStreamer here, deliberately: the console never writes
// through a fleet's store door, and streaming would need a server side in
// internal/edge/storedoor.go. release.PutObjectFrom falls back to Put for
// bodies up to PutFromFallbackMax (geoip spec §4.1).

// Put mirrors the door's CAS mapping exactly (storedoor.go's
// putPrecondition / F4): ifMatch == "" sends If-None-Match: * (create-only,
// the contract's only form of an unconditional-looking write), a non-empty
// ifMatch sends If-Match: <etag> (replace-only). There is no unconditional
// Put on this wire, so this client never attempts one. A lost race (412)
// maps back to release.ErrCASConflict — the same error a direct DirStore or
// S3Store Put would return, so a heartbeat or binding-takeover CAS loop
// behaves identically whether or not it is going through the door.
func (s *store) Put(ctx context.Context, key string, body []byte, ifMatch string) (string, error) {
	req, err := s.newRequest(ctx, http.MethodPut, s.objectURL(key), bytes.NewReader(body))
	if err != nil {
		return "", err
	}
	req.ContentLength = int64(len(body))
	if ifMatch == "" {
		req.Header.Set("If-None-Match", "*")
	} else {
		req.Header.Set("If-Match", ifMatch)
	}
	resp, err := s.client.Do(req)
	if err != nil {
		return "", errorf("put %s: %w", key, err)
	}
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
	switch resp.StatusCode {
	case http.StatusOK:
		return resp.Header.Get("ETag"), nil
	case http.StatusPreconditionFailed:
		return "", fmt.Errorf("fleetapi: %s: %w", key, release.ErrCASConflict)
	default:
		return "", errorf("put %s: unexpected status %d: %s", key, resp.StatusCode, strings.TrimSpace(string(respBody)))
	}
}

// Delete is idempotent, matching release.Store's contract: the door
// (storedoor.go) always answers 204 for an in-scope key, deleted or not,
// which is where the idempotency lives — NOT in this client folding a 404
// into success. A 404 here is only ever a refusal (bad token, bad name, an
// out-of-scope key, a malformed key, a misrouted base): it is never "already
// gone", because "already gone" is exactly the case the door answers 204.
// Treating it as success would make a mis-credentialled client report every
// delete as having worked.
func (s *store) Delete(ctx context.Context, key string) error {
	req, err := s.newRequest(ctx, http.MethodDelete, s.objectURL(key), nil)
	if err != nil {
		return err
	}
	resp, err := s.client.Do(req)
	if err != nil {
		return errorf("delete %s: %w", key, err)
	}
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
	if resp.StatusCode != http.StatusNoContent {
		return errorf("delete %s: unexpected status %d: %s", key, resp.StatusCode, strings.TrimSpace(string(respBody)))
	}
	return nil
}

// List is the door's /store/list — see listDecode. Note the spec's callout:
// the door 404s a root listing (List("")) the same as any other out-of-scope
// prefix (aclListScope refuses an empty prefix outright), and this client
// does not special-case it: an empty-prefix caller gets exactly that error,
// same as any other caller would over a direct S3Store asking for a prefix
// its bucket policy refuses.
func (s *store) List(ctx context.Context, prefix string) ([]string, error) {
	return s.listDecode(ctx, "/store/list", prefix)
}

// ListDirs is the door's /store/dirs (the delimiter-aware listing).
func (s *store) ListDirs(ctx context.Context, prefix string) ([]string, error) {
	return s.listDecode(ctx, "/store/dirs", prefix)
}

func (s *store) listDecode(ctx context.Context, path, prefix string) ([]string, error) {
	req, err := s.newRequest(ctx, http.MethodGet, s.listURL(path, prefix), nil)
	if err != nil {
		return nil, err
	}
	resp, err := s.client.Do(req)
	if err != nil {
		return nil, errorf("list %s: %w", prefix, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
		return nil, errorf("list %s: unexpected status %d: %s", prefix, resp.StatusCode, strings.TrimSpace(string(respBody)))
	}
	// The door never sends null (storedoor.go: "an empty listing is []"), but
	// decoding into a nil slice handles either shape the same way a caller
	// ranging over the result cares about: zero iterations.
	var out []string
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, errorf("list %s: decode response: %w", prefix, err)
	}
	return out, nil
}