dbmirror

type CollectionResult struct {
	Collection string `json:"collection"`
	Action     string `json:"action"`
	Selected   bool   `json:"selected"`
	Note       string `json:"note,omitempty"`
	Query      string `json:"query,omitempty"`
	Count      *int64 `json:"count,omitempty"`
	// CountAtLeast says Count stopped at the read budget: there are at least that many.
	CountAtLeast bool     `json:"count_at_least,omitempty"`
	Records      int64    `json:"records"`
	Rejected     int64    `json:"rejected,omitempty"`
	Masked       []string `json:"masked_fields,omitempty"`
	// BelowMissingParent counts records whose parent document does not exist
	// in the source (Firestore keeps such sub-collections).
	BelowMissingParent int64 `json:"below_missing_parent,omitempty"`
	// OtherParents counts documents of the collection that were read but not
	// copied because their path is not one the policy's paths allow, and
	// OtherParentPaths shows those paths with every unpinned id as "*".
	OtherParents     int64    `json:"other_parents,omitempty"`
	OtherParentPaths []string `json:"other_parent_paths,omitempty"`
	// IDTooLong counts documents not copied because their record file name
	// (the encoded id) is longer than 255 bytes, or their path longer than the
	// system writes: file per record does not hold them.
	IDTooLong int64 `json:"not_copied_id_too_long,omitempty"`
	// Resumed says part of the collection was read by an earlier run.
	Resumed  bool `json:"resumed,omitempty"`
	Complete bool `json:"complete"`
	// contains filtered or unexported fields
}

type Definitions struct {
	Dir   string // absolute folder of the definitions
	Specs []*Spec
	// contains filtered or unexported fields
}

type Doc struct {
	// Path is the document path relative to the database (a/1/b/2).
	Path string
	// Data holds the fields as the Google Firestore SDK returns them.
	Data map[string]any
}

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

type KeyEncoding interface {
	// Name identifies the encoding in the output's state.
	Name() string
	// Encode is the file name of id.
	Encode(id string) string
	// Decode is the id of a file name, and false for a name Encode never writes.
	Decode(name string) (string, bool)
}

type Options struct {
	// Output is the folder the inGitDB database is written to. Not used by a dry run.
	Output string
	// Collections, when not empty, copies only these defined collections
	// (a collection id path, or "<path>/**" for it and every collection below it).
	Collections []string
	// Under, when set, copies only the documents at or below this path: a
	// document path (spaces/abc) or a collection path (spaces/abc/ext).
	Under string
	// DryRun counts the documents of each collection and writes nothing.
	DryRun bool
	// MaxReads stops the run before more than this many Firestore reads (0: no limit).
	MaxReads int64
	// PageSize is how many documents one request reads (default DefaultPageSize).
	PageSize int
	// KeepRejected also writes each rejected document under
	// .datatug-mirror/rejected/, as read with only the policy's masks applied:
	// its undeclared fields and the values that break its definition are
	// written in clear. By default only its path, reasons and declared field
	// names are kept, in the report.
	KeepRejected bool
	// ContinueOnLongIDs copies the rest when a document's id is too long for
	// one file per record, and reports it (the run is then incomplete),
	// instead of failing at the first one.
	ContinueOnLongIDs bool
	// Prune deletes the record files whose document no longer exists, in the
	// collections this run read completely. By default they are only reported.
	Prune bool
	// Restart ignores the resume state an earlier run left (see Resume).
	Restart bool
	// Snapshot reads every document as it was when the run (or the run it
	// resumes, within the hour) started, when the source can.
	Snapshot bool
	// Source is how the source is shown in the report (never a credential).
	Source string
	// Identity is the database read. The output records the identity of the
	// source it was created from, and every later run into it, its resume
	// and its prune, must read the same one.
	Identity SourceIdentity
	// Log receives one line per collection and the summary (nil: discarded).
	Log io.Writer
	// Progress, when set, receives one line per page read.
	Progress io.Writer
}

type OutsideRead struct {
	Collection string `json:"collection"`
	Defined    bool   `json:"defined"`
	Documents  int64  `json:"documents"`
}

type Policy struct {
	Format      string              `yaml:"format"`
	Definitions string              `yaml:"definitions,omitempty"`
	Output      string              `yaml:"output,omitempty"`
	Copy        []string            `yaml:"copy,omitempty"`
	Exclude     []string            `yaml:"exclude,omitempty"`
	Mask        map[string][]string `yaml:"mask,omitempty"`
	Paths       map[string][]string `yaml:"paths,omitempty"`

	// Path is the file the policy was read from ("" when built in code).
	Path string `yaml:"-"`
}

type Query struct {
	// Collection is a collection path (a root collection id, or a/1/b for the
	// collection b of the document a/1), or, for a group, a collection id.
	Collection string
	// Group reads every collection named Collection, at any depth.
	Group bool
	// Under, when set, keeps a group query to the documents at or below this
	// document path: a range on the document name, so documents of a sibling
	// whose id starts with the same text (a/1x below a/1) are not read.
	Under string
	// After continues the read after this document path.
	After string
	// Limit is, for Page, the most documents to return (> 0); for Count, the
	// most documents to count (0: all of them).
	Limit int
}

type Rejection struct {
	Path       string   `json:"path"`
	Collection string   `json:"collection"`
	Reasons    []string `json:"reasons"`
	Fields     []string `json:"fields,omitempty"`
}

type Report struct {
	Format         string          `json:"format"`
	Source         string          `json:"source"`
	SourceIdentity *SourceIdentity `json:"source_identity,omitempty"`
	Under          string          `json:"under,omitempty"`
	DryRun         bool            `json:"dry_run,omitempty"`
	Complete       bool            `json:"complete"`
	BudgetReached  bool            `json:"budget_reached,omitempty"`
	// Resumed says the run continued one that stopped at its read budget.
	Resumed    bool     `json:"resumed,omitempty"`
	ReadTime   string   `json:"read_time,omitempty"`
	Incomplete []string `json:"incomplete,omitempty"`
	// Reads are this run's billed reads; ReadsTotal adds those of the runs it resumed.
	Reads                    int64              `json:"reads"`
	ReadsTotal               int64              `json:"reads_total,omitempty"`
	MaxReads                 int64              `json:"max_reads,omitempty"`
	Records                  int64              `json:"records"`
	Collections              []CollectionResult `json:"collections"`
	Rejected                 []Rejection        `json:"rejected,omitempty"`
	UndefinedRootCollections []string           `json:"undefined_root_collections,omitempty"`
	Outside                  []OutsideRead      `json:"read_outside_selection,omitempty"`
	Stale                    []string           `json:"stale_record_files,omitempty"`
	Pruned                   []string           `json:"pruned_record_files,omitempty"`
	Validation               []string           `json:"validation_errors,omitempty"`

	// Written and Unchanged count record files of this run (not in the
	// report file: they differ between a first run and a re-run).
	Written   int64 `json:"-"`
	Unchanged int64 `json:"-"`
}

type Source interface {
	// RootCollections lists the ids of the root collections.
	RootCollections(ctx context.Context) ([]string, error)
	// Page returns at most q.Limit documents of q, in document-path order.
	Page(ctx context.Context, q Query) ([]Doc, error)
	// Get returns the document at path, or nil when there is none.
	Get(ctx context.Context, path string) (*Doc, error)
	// Count returns how many documents q (without After) matches, counting at
	// most q.Limit of them when it is set.
	Count(ctx context.Context, q Query) (int64, error)
}

type SourceIdentity struct {
	Project  string `json:"project"`
	Database string `json:"database"`
	Emulator string `json:"emulator,omitempty"`
}

type Spec struct {
	// ID is the collection ids of the path joined by "/".
	ID string
	// Segments are the collection ids of the path, root first.
	Segments []string
	// Def is the inGitDB definition of this collection.
	Def *ingitdb.CollectionDef
	// Unsupported, when not empty, says why records of this collection cannot
	// be written; the collection is then reported and never read.
	Unsupported string
	// contains filtered or unexported fields
}