plugin

type Address struct {
	Network string // "unix" | "tcp"
	Target  string // socket path, or host:port, or full URL for remote
	URL     string // base URL to put in front of /v1
}

type Capabilities struct {
	Range     bool `json:"range"`
	Write     bool `json:"write"`
	Delete    bool `json:"delete"`
	Move      bool `json:"move"`
	Copy      bool `json:"copy"`
	Mkdir     bool `json:"mkdir"`
	SetMtime  bool `json:"set_mtime"`
	Watch     bool `json:"watch"`
	Presign   bool `json:"presign"`
	Multipart bool `json:"multipart"`
}

type Client struct {
	// contains filtered or unexported fields
}

type DescribeResponse struct {
	// Protocol must equal ProtocolVersion.
	Protocol int `json:"protocol"`
	// Name is the driver's short identifier: [a-z0-9][a-z0-9_-]{0,31}. The
	// storage registry knows it as DriverPrefix+Name.
	Name string `json:"name"`
	// Version is the plugin's own version string, shown in the admin list.
	Version string `json:"version,omitempty"`
	// Label is the human name for the driver picker (English; the plugin may
	// also ship an I18nKey the host's catalogue does not know — the label is
	// the fallback surfaces already apply).
	Label string `json:"label"`
	// Fields is the config form, in exactly the shape storage.Descriptor uses
	// so the Connections page can render it without knowing the driver.
	Fields       []storage.Field `json:"fields"`
	Capabilities Capabilities    `json:"capabilities"`
}

type ErrorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message,omitempty"`
}

type Event struct {
	Op   string `json:"op"` // create | modify | delete | move
	Path string `json:"path"`
	From string `json:"from,omitempty"`
}

type Handle interface {
	// Client returns the live client, or an error naming why the plugin is
	// unavailable right now (stopped, crashed and backing off, disabled).
	Client() (*Client, error)
	// DriverName is DriverPrefix+name.
	DriverName() string
}

type InstanceRequest struct {
	Config map[string]any `json:"config"`
}

type InstanceResponse struct {
	Instance string `json:"instance"`
}

type ListResponse struct {
	Objects []Object `json:"objects"`
}

type Manager struct {
	// contains filtered or unexported fields
}

type MoveRequest struct {
	Src string `json:"src"`
	Dst string `json:"dst"`
}

type MtimeRequest struct {
	Path  string    `json:"path"`
	Mtime time.Time `json:"mtime"`
}

type MultipartCompleteRequest struct {
	Path     string          `json:"path"`
	UploadID string          `json:"upload_id"`
	Parts    []MultipartPart `json:"parts,omitempty"`
}

type MultipartInitRequest struct {
	Path      string `json:"path"`
	TotalSize int64  `json:"total_size"`
	PartCount int    `json:"part_count"`
}

type MultipartInitResponse struct {
	UploadID string   `json:"upload_id"`
	PartURLs []string `json:"part_urls,omitempty"`
}

type MultipartPart struct {
	PartNumber int    `json:"part_number"`
	Etag       string `json:"etag"`
}

type MultipartPartResponse struct {
	Etag string `json:"etag"`
}

type Object struct {
	Path     string            `json:"path"`
	Name     string            `json:"name"`
	Size     int64             `json:"size"`
	Kind     string            `json:"kind"` // "file" | "dir" | "symlink"
	Mime     string            `json:"mime,omitempty"`
	Etag     string            `json:"etag,omitempty"`
	Mtime    time.Time         `json:"mtime,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Options struct {
	Store db.Store
	// Dir is where binary plugins live: <data-dir>/plugins.
	Dir string
	// SecretKey seals remote plugins' bearer tokens (secretbox). Empty means
	// a remote plugin cannot be registered — the token would have to be
	// stored in plaintext, and this codebase does not do that.
	SecretKey string
	Log       *slog.Logger
	// MaxBinaryBytes caps an uploaded/downloaded plugin. 0 → 512 MiB.
	MaxBinaryBytes int64
	// HTTP downloads plugins from URLs. Nil → a guarded client with a
	// timeout that refuses private, loopback and link-local targets (after
	// DNS, and on every redirect hop) — a plugin URL must not become a probe
	// of the server's own network. Supplying a client lifts that guard; it
	// exists for tests and for an embedder that has its own egress policy.
	HTTP *http.Client
	// Conformance is enforce (default), warn or off.
	Conformance string
	// MaxInFlight bounds concurrent operations per plugin (0 → the default).
	MaxInFlight int
	// TrustedKeys are ed25519 public keys (hex or base64) that may sign a
	// plugin binary. When ANY key is configured, an unsigned or badly signed
	// binary is refused at install: the sha256 only proves the file has not
	// changed since it arrived, never that it came from someone you trust.
	TrustedKeys []string
}

type PathRequest struct {
	Path string `json:"path"`
}

type PresignRequest struct {
	Path string `json:"path"`
	// Size is the object size for an upload (-1 when unknown).
	Size int64 `json:"size,omitempty"`
	// TTLSeconds is how long a download URL should stay valid.
	TTLSeconds int64 `json:"ttl_s,omitempty"`
}

type PresignResponse struct {
	URL       string            `json:"url"`
	Method    string            `json:"method,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	ExpiresAt time.Time         `json:"expires_at"`
}

type ProbeResult struct {
	// Name is the capability or behaviour probed ("read", "write", "range"…).
	Name string `json:"name"`
	// Status is pass | fail | skip.
	Status string `json:"status"`
	// Detail says what happened — for a failure, precisely enough to fix it.
	Detail string `json:"detail,omitempty"`
	// Took is how long the probe ran. ⚠ NOT serialised: encoding/json has no
	// marshaller for time.Duration and writes the raw int64, so a field named
	// took_ms carrying a Duration is off by a million — measured by the admin
	// page reading nanoseconds as milliseconds. TookMS below is what goes on
	// the wire, and it really is milliseconds.
	Took   time.Duration `json:"-"`
	TookMS int64         `json:"took_ms"`
}

type Process struct {
	Name    string
	Binary  string // absolute path
	Token   string
	SockDir string // private directory the plugin may create its socket in
	Log     *slog.Logger

	// OnUp is called (from the supervisor goroutine) each time the plugin has
	// printed its handshake and answered nothing yet — the manager describes
	// it here and decides whether it is acceptable. Returning an error stops
	// the plugin for good (a plugin that fails validation will fail it again;
	// restarting would only churn).
	OnUp func(ctx context.Context, c *Client) error
	// OnDown is called each time the process is gone (exit, kill, failed
	// handshake), before any restart.
	OnDown func(err error)
	// contains filtered or unexported fields
}

type RejectedError struct {
	// contains filtered or unexported fields
}

type Report struct {
	// Verified is true when every declared capability passed.
	Verified bool `json:"verified"`
	// Scratch says where the probes ran: "selftest" (the plugin's own
	// throwaway area) or "storage" (a folder inside a real storage).
	Scratch string        `json:"scratch"`
	Results []ProbeResult `json:"results"`
	RanAt   time.Time     `json:"ran_at"`
}

type Stats struct {
	InFlight int64 `json:"in_flight"`
	Waited   int64 `json:"waited"`
	Rejected int64 `json:"rejected"`
	Max      int   `json:"max_in_flight"`
}

type Status struct {
	*model.Plugin
	State        string        `json:"state"`
	StateError   string        `json:"state_error,omitempty"`
	Restarts     int           `json:"restarts"`
	Capabilities *Capabilities `json:"capabilities,omitempty"`
	Label        string        `json:"label,omitempty"`
	FieldCount   int           `json:"field_count"`
	// InUse counts storage rows on this plugin's driver — shown before a
	// remove so the admin knows what will stop working.
	InUse int `json:"in_use"`
	// Conformance is the last verification of the plugin's own claims. Nil
	// when it has not been probed (an older row, or probing is off).
	Conformance *Report `json:"conformance,omitempty"`
	// Load is what this plugin is doing right now: in-flight operations, and
	// how often callers have had to wait or been refused a slot. A plugin
	// that is merely SLOW shows up here long before it shows up as an error.
	Load Stats `json:"load"`
}