extract

type Exploder interface {
	// MIMEs returns the exact MIME types this exploder claims. Registration
	// panics on a duplicate claim, so two backends cannot silently fight.
	MIMEs() []string

	// Explode calls yield once per surviving member, in archive order.
	//
	// Takes io.ReaderAt + size rather than io.Reader because a container
	// format needs random access to read its directory; a backend fed a stream
	// buffers to os.TempDir() and removes what it writes.
	//
	// Implementations MUST enforce lim while streaming, and MUST NOT recurse
	// into a member that is itself an archive — nesting depth is 0, so a
	// zip-of-zips cannot re-enter. An error returned by yield aborts the walk
	// and is returned unchanged.
	Explode(r io.ReaderAt, size int64, lim Limits, yield func(Member) error) (Summary, error)
}

type Extractor interface {
	// MIMEs returns the exact MIME types this extractor claims. Registration
	// panics on a duplicate claim, so two backends cannot silently fight.
	MIMEs() []string
	// Extract reads r to EOF and returns the text. Implementations must not
	// perform network or filesystem I/O.
	Extract(r io.Reader) (Result, error)
}

type Limits struct {
	// MaxUncompressedTotal caps the whole archive's expanded size.
	MaxUncompressedTotal int64
	// MaxMemberBytes caps a single member.
	MaxMemberBytes int64
	// MaxMembers caps how many members are yielded. Reaching it TRUNCATES —
	// Summary.Truncated — rather than failing the archive: a partial support
	// bundle is still useful, provided the caller is told it is partial.
	MaxMembers int
	// MaxRatio caps expanded÷compressed, evaluated per member AND across the
	// archive, so neither one enormous member nor a thousand modest ones gets
	// through on the other's budget.
	MaxRatio int
	// MaxWallClock bounds the whole explode. It covers the bomb that stays
	// under every byte bound by decompressing slowly, which no size check can
	// see.
	MaxWallClock time.Duration
}

type Member struct {
	// Name is the sanitized, archive-relative path. Never absolute, never
	// containing "..", and still UNTRUSTED text: it reaches an agent's context
	// and must be treated as such by whoever renders it.
	Name string
	// Size is the uncompressed size actually produced, not the size the
	// archive's header claimed.
	Size int64
	// MIME is SNIFFED from the member's first bytes, never derived from Name.
	//
	// This is where the archive path differs from a direct upload, where the
	// channel supplies a MIME we have no better source for: here WE assign it,
	// so trusting an attacker-chosen extension would let a filename decide
	// which parser runs downstream.
	MIME string
	// Open returns the member's bytes. The caller owns closing it. Reading
	// past a limit returns ErrArchiveBomb mid-stream.
	Open func() (io.ReadCloser, error)
}

type Result struct {
	// Text is the extracted plain text, suitable for an agent to read.
	Text string
	// Pages is a page/slide count when the format has one, else 0. Reported to
	// the agent in the attachment manifest so it can judge scale before reading.
	Pages int
}

type SkipReason string

type Summary struct {
	// Members is how many were yielded.
	Members int
	// Truncated is set when a bound stopped the walk early.
	Truncated bool
	// TruncatedReason names the bound, for a caller to state plainly.
	TruncatedReason string
	// TruncatedMember names the member whose COPY was cut, when the walk
	// stopped inside one rather than between them.
	//
	// Without it a member cut mid-copy is indistinguishable from a whole one:
	// its part is already on the wire, and the consumer stores it, runs text
	// extraction over it and lists it as complete. The archive-level Truncated
	// flag says SOMETHING was cut; this says WHICH, which is what a consumer
	// needs to mark that one row partial instead of guessing.
	//
	// Empty when the walk stopped BETWEEN members (the member-count bound), or
	// when nothing was truncated at all.
	TruncatedMember string
	// Skipped counts refused entries by reason. Counts, never names — see
	// SkipReason.
	Skipped map[SkipReason]int
}