zipstream

type Member struct {
	// Name is the path inside the archive, forward-slashed and relative.
	// Cleaned and de-duplicated by Write; a name that escapes the archive
	// root is rejected there, not here.
	Name string
	// Size is what the caller believed the member's size to be. It is used
	// for reporting and progress only — never for a length header, and never
	// to decide the archive is finished.
	Size int64
	// Mtime is stamped into the entry so an unpacked tree keeps its dates.
	// The zero value writes the zip epoch, which is what a bare zw.Create
	// does and is only ever ugly, never wrong.
	Mtime time.Time
	// Open yields the member's bytes.
	Open func(ctx context.Context) (io.ReadCloser, error)
}

type Options struct {
	// Gate is asked, at most once per GateEvery, whether the build should
	// still be running. A non-nil error from it ends Write with that error.
	// It is consulted BETWEEN members and DURING a member's copy, because
	// "between members" is no bound at all on a set whose one member is
	// 15 GB.
	Gate func() error
	// GateEvery throttles Gate. Zero or negative means NO throttle: the gate
	// is asked at every opportunity.
	//
	// ⚠ Unthrottled is the default on purpose, and it is the cheap direction.
	// A gate is a caller's own predicate — sharezip's is a mutex and a map
	// lookup — so asking it once per 32 KiB read costs microseconds per
	// gigabyte, while a throttle that is accidentally in force is a build
	// that keeps running for seconds after everyone stopped caring. Callers
	// whose gate is genuinely expensive set an interval; nobody has to
	// remember to switch responsiveness ON.
	GateEvery time.Duration

	// OnMember runs after each member is fully written. Progress counters
	// hang off this.
	OnMember func(m Member)

	// OnSkip runs for each member that was dropped or truncated. A caller
	// that ignores this is choosing to lose files silently.
	OnSkip func(s Skip)

	// Flush is called after each member. Over HTTP this is what makes the
	// browser show a growing download instead of a stalled one while a slow
	// storage is being read.
	Flush func()

	// Manifest, when non-empty, is the name of an extra text member appended
	// to the archive listing every Skip. It is written ONLY if something was
	// skipped, so a clean archive gains nothing. This is the honest half of
	// "keep going when one member disappears": the archive stays valid and
	// the person opening it can see what is not in it.
	Manifest string
}

type Skip struct {
	Name string
	// Err is why. Never nil.
	Err error
	// Partial is true when the failure happened AFTER bytes had already been
	// written into the entry — the difference between "this file is missing
	// from your archive" and "this file is in your archive and it is short".
	// A caller that reports skips must keep them apart: the second one is the
	// dangerous kind, because the entry looks perfectly well-formed to every
	// unzip tool on earth.
	Partial bool
	// Written is how many bytes reached the entry before the failure.
	Written int64
}