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 Feed struct {
	Name     string                `json:"name"`
	Version  string                `json:"version"`
	Filex    string                `json:"filex,omitempty"`
	Notes    string                `json:"notes,omitempty"`
	Binaries map[string]FeedBinary `json:"binaries"`
}

type FeedBinary struct {
	URL    string `json:"url"`
	SHA256 string `json:"sha256"`
	// Signature is the detached ed25519 signature over the sha256, for an
	// instance that only runs signed plugins (FILEX_PLUGIN_TRUSTED_KEYS).
	Signature string `json:"signature,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
	// Platform is the GOOS/GOARCH key a source's build is chosen by
	// (updates.go). Empty = the running one; tests set it.
	Platform 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"`
	// Update is what the last check of the plugin's source found
	// (updates.go); absent for a plugin without a source, or before the
	// first check.
	Update *UpdateInfo `json:"update,omitempty"`
}

type UpdateHooks struct {
	// Range judges a feed's `filex` range against the running filex
	// (wasmplugin.JudgeFilexRange). Nil = no range is checked.
	Range func(rng string) (ok bool, requires, filex string, err error)
	// Announce rings the administrators' bell, once per newer version.
	Announce func(ctx context.Context, name, version, notes string)
}

type UpdateInfo struct {
	CheckedAt *time.Time `json:"checked_at,omitempty"`
	Status    string     `json:"status"`
	// Version: the newer version (available, incompatible).
	Version string `json:"version,omitempty"`
	// Requires: incompatible — the range that version declares.
	Requires string `json:"requires,omitempty"`
	// Notes: the feed's notes for Version, plain text.
	Notes string `json:"notes,omitempty"`
	// SHA256: the build for this platform (available).
	SHA256 string `json:"sha256,omitempty"`
	// Platform the build was chosen for ("linux/amd64").
	Platform string `json:"platform,omitempty"`
	// Error: check_failed — why.
	Error string `json:"error,omitempty"`
	// Announced is "<status>@<version>" once the administrators were told.
	Announced string `json:"announced,omitempty"`
}

type UpdateReport struct {
	CheckedAt time.Time `json:"checked_at"`
	Checked   int       `json:"checked"`
	Available []string  `json:"available"`
	Failed    []string  `json:"failed"`
}