pagewalk

type Address interface {
	// FollowURL moves the address to a next link. It refuses a link whose
	// scheme or host differs from the one the walk is pinned to.
	FollowURL(next string) error
	// Param reads a query parameter of the address ("" when unset).
	Param(name string) string
	// SetParam sets a query parameter of the address.
	SetParam(name, value string)
	// Target is the request the address currently points at.
	Target() Target
}

type AddressSpec struct {
	BaseURL      string
	Path         string
	Query        map[string]any
	Body         any
	WalkBodyURL  bool
	ValidatePath func(string) error
}

type InlineMerge struct {
	Limit int64
	// Rendered measures the merged array as the caller's tool result
	// will render it. The limit is expressed against that rather than
	// against the compact bytes the pages hold, because what a client
	// accepts is the rendered result and the indentation between the two
	// is several times the compact size (issue #1606). nil measures the
	// compact bytes.
	Rendered func(items []json.RawMessage) int64
	// contains filtered or unexported fields
}

type Options struct {
	Paginate  PaginateInput
	Address   AddressSpec
	Requester Requester
	// Authorize is the route policy check run on every page's target.
	// nil when the deployment installed no policy.
	Authorize func(Target) error
	Sink      Sink
	// Now is the clock Retry-After dates are read against; nil is
	// time.Now.
	Now func() time.Time
}

type Page struct {
	Status      int
	Header      http.Header
	ContentType string
	Body        []byte
}

type PaginateInput struct {
	// Items is the key of the array merged across pages ("data", "items",
	// "results", "value"), a dotted path to a nested one ("result.items"),
	// or "$" when the page body is the array. Required: guessing the key
	// is how a merged result silently becomes a list of envelopes.
	Items string `json:"items"`
	// CursorParam is the query parameter a body cursor (next_cursor,
	// nextPageToken, ...) is sent back as. A cursor signal on a page that
	// names no CursorParam and no PageParam fails the walk.
	CursorParam string `json:"cursor_param,omitempty"`
	// PageParam is the query parameter advanced when a page carries no
	// next signal (?page=N, ?offset=N). Its starting value must be present
	// in query_params; the first page is requested exactly as given.
	PageParam string `json:"page_param,omitempty"`
	// PageStep is what PageParam is advanced by per page. 1 (the default)
	// suits ?page=N; the page size suits ?offset=N.
	PageStep int `json:"page_step,omitempty"`
	// MaxPages bounds the walk. 0 means defaultMaxPages; the ceiling is
	// maxMaxPages. Reaching it is reported as stopped_by "max_pages", with
	// the signal for the next page in `pagination`.
	MaxPages int `json:"max_pages,omitempty"`
}

type PaginationInfo struct {
	HasMore    bool   `json:"has_more,omitempty"`
	NextCursor string `json:"next_cursor,omitempty"`
	NextURL    string `json:"next_url,omitempty"`
	Source     string `json:"source,omitempty"`
}

type Requester interface {
	Do(ctx context.Context, target Target) (*http.Response, error)
	ReadPage(resp *http.Response) (Page, error)
}

type Sink func(items []json.RawMessage) error

type Target struct {
	Path  string
	Query map[string]any
	Body  any
}

type Walk struct {

	// Stats is the page count, item count, and why the walk stopped.
	Stats WalkStats
	// Resume is the signal for the page after the last merged one when
	// the walk stopped early (max_pages or max_bytes); nil at the end.
	Resume *PaginationInfo
	// Lead is the signal that addressed the most recent page: the walk's
	// "final cursor" for provenance.
	Lead *PaginationInfo
	// Last is the last page read, whose status and headers the inline
	// output reports as a single call's would be.
	Last Page
	// contains filtered or unexported fields
}

type WalkStats struct {
	PagesFetched int    `json:"pages_fetched"`
	ItemsMerged  int    `json:"items_merged"`
	StoppedBy    string `json:"stopped_by"`
}