rules

type Action struct {
	PackageName string `json:"packageName,omitempty"`
	DownloadDir string `json:"downloadDir,omitempty"`
	Filename    string `json:"filename,omitempty"`
	Comment     string `json:"comment,omitempty"`
	Priority    *int   `json:"priority,omitempty"`
	AutoExtract *bool  `json:"autoExtract,omitempty"`
	Chunks      *int   `json:"chunks,omitempty"`

	// Reject drops the link instead of taking it. Reason is shown to the user
	// alongside the rule's name; when it is empty Check writes one, because a
	// rejection nobody can explain is the behaviour this package exists to
	// avoid.
	Reject bool   `json:"reject,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type ActionGrammar struct {
	// ID is the JSON field name on Action, so the form addresses the same key the
	// engine reads and a typo is a compile error over here rather than a control
	// that quietly does nothing.
	ID string `json:"id"`
	// Kind is how it is edited: template, int, bool or reject.
	Kind string `json:"kind"`
	// Flavour is which of the two engines honours it: "packagizer", "filter", or
	// empty for both.
	Flavour string `json:"flavour,omitempty"`
	// Min and Max bound an int action, so the form clamps to the same numbers
	// actionProblems refuses outside of.
	Min *int `json:"min,omitempty"`
	Max *int `json:"max,omitempty"`
}

type Candidate struct {
	Filename string
	URL      string
	Hoster   string
	Source   string
	Filetype string
	Filesize int64
	Package  string
	Added    time.Time
}

type Category struct {
	ID string `json:"id"`
	// Extensions is what the category covers, without dots, lower case, in the
	// order the editor should list them. It is shown so somebody can check
	// whether their format is in there before trusting the chip.
	Extensions []string `json:"extensions"`
	// Pattern is the exact value the editor writes into Condition.Value with
	// OpMatches on FieldFiletype. Generated here rather than in the interface so
	// that recognising a stored rule as a category is a string comparison against
	// this same field, and cannot drift into "nearly the same pattern".
	Pattern string `json:"pattern"`
}

type Condition struct {
	Field Field  `json:"field"`
	Op    Op     `json:"op"`
	Value string `json:"value,omitempty"`
	Min   int64  `json:"min,omitempty"`
	// Max of zero means "no upper bound". A half-filled range is the normal
	// shape of "at least 500 MB", and reading the empty box as zero would give
	// the user a rule that can never match anything.
	Max int64 `json:"max,omitempty"`
}

type Effect struct {
	Package     string `json:"package,omitempty"`
	Dir         string `json:"dir,omitempty"`
	Filename    string `json:"filename,omitempty"`
	Comment     string `json:"comment,omitempty"`
	Priority    *int   `json:"priority,omitempty"`
	AutoExtract *bool  `json:"autoExtract,omitempty"`
	Chunks      *int   `json:"chunks,omitempty"`
	// Matched names the rules that fired, in the order they fired, so the
	// interface can answer "why did this land here" without re-running anything.
	Matched []string `json:"matched,omitempty"`
}

type Field string

type FieldGrammar struct {
	ID Field `json:"id"`
	// Ops is exactly the set compileCondition accepts for this field, in the
	// order the form should list them.
	Ops []Op `json:"ops"`
	// Numeric marks the field whose values are byte counts rather than text, so
	// the form knows to offer a size box instead of a text box. Turning "700 MB"
	// into a number is the interface's job: a parser down here would disagree
	// with the one up there sooner or later.
	Numeric bool `json:"numeric,omitempty"`
	// Groups marks a field a capture group can be read from, which is every field
	// the "matches" operator applies to.
	Groups bool `json:"groups,omitempty"`
}

type Grammar struct {
	Fields    []FieldGrammar  `json:"fields"`
	Operators []OpGrammar     `json:"operators"`
	Actions   []ActionGrammar `json:"actions"`
	Variables []Variable      `json:"variables"`
	// Categories are the file-type shorthands the editor offers on a filetype
	// condition. They expand into ordinary conditions and are described here for
	// the same reason everything else in this file is: the pattern a category
	// stands for has to be the one the engine will actually run.
	Categories []Category `json:"categories"`
	Limits     Limits     `json:"limits"`
}

type Limits struct {
	PriorityMin int `json:"priorityMin"`
	PriorityMax int `json:"priorityMax"`
	MaxChunks   int `json:"maxChunks"`
	MaxPattern  int `json:"maxPattern"`
}

type LinkReport struct {
	URL      string `json:"url"`
	Filename string `json:"filename"`
	// Matched is the rules that fired, by index, in the order they fired.
	Matched []int `json:"matched"`
	// Effect and Verdict are exactly what the two engines would return, from the
	// same code that staging calls.
	Effect  Effect  `json:"effect"`
	Verdict Verdict `json:"verdict"`
	// Result is where the link would end up, with the fields no rule had an
	// opinion about filled in from the link itself. Effect leaves those empty and
	// means "unchanged", which is right for the caller applying it and useless to
	// somebody asking what the answer is.
	Result Outcome `json:"result"`
}

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

type Op string

type OpGrammar struct {
	ID Op `json:"id"`
	// Value is set when the operator needs the single Value box filled.
	Value bool `json:"value,omitempty"`
	// Range is set when it needs Min and Max instead. Both are never set at once.
	Range bool `json:"range,omitempty"`
	// Regex marks the operator whose value is a pattern, so the form can offer a
	// pattern box and say what a bad one costs.
	Regex bool `json:"regex,omitempty"`
}

type Outcome struct {
	Package  string `json:"package"`
	Filename string `json:"filename"`
}

type Problem struct {
	Index   int    `json:"index"` // position in Set.Rules, zero-based
	Rule    string `json:"rule"`  // the rule's name, or its position when unnamed
	Message string `json:"message"`
	// Condition is which condition the problem is about, counting from 1, and 0
	// when it is about the action or the rule as a whole.
	//
	// The number is already in Message, and the editor needs it as data: put a
	// message under the rule and the user still has to find which of six rows has
	// the unparsable pattern in it. The alternative is a client that parses
	// "condition 3 (filename): ..." back out of a sentence, which breaks the first
	// time the wording changes or the interface is translated.
	Condition int `json:"condition,omitempty"`
}

type Report struct {
	// Problems is every rule Compile could not use, keyed to its position in the
	// set so the editor can put the message on the rule instead of in a list at
	// the bottom of the page that nobody connects to anything.
	Problems []Problem `json:"problems"`
	// Rules mirrors the set one entry per rule, in order, including the ones that
	// are switched off or broken. A rule missing from the answer would look like a
	// rendering fault; one that is present and says why it did nothing does not.
	Rules []RuleReport `json:"rules"`
	// Links is one entry per sample, in the order they were given.
	Links []LinkReport `json:"links"`
	// Disabled reports that the set's master switch is off, so the editor can say
	// that nothing below is being applied. The rest of the report is still filled
	// in as though it were on: a set cannot be repaired while it is off if being
	// off also hides what is wrong with it.
	Disabled bool `json:"disabled,omitempty"`
}

type Rule struct {
	Name       string      `json:"name,omitempty"`
	Disabled   bool        `json:"disabled,omitempty"`
	Conditions []Condition `json:"conditions,omitempty"`
	Action     Action      `json:"action"`
}

type RuleReport struct {
	Index    int    `json:"index"`
	Name     string `json:"name"`
	Disabled bool   `json:"disabled,omitempty"`
	// Problems is this rule's share of Report.Problems. It is duplicated rather
	// than referenced because the editor renders it next to the rule, and a
	// client filtering a flat list by index is a filter every client has to write.
	Problems []Problem `json:"problems,omitempty"`
	// Matched is how many of the samples this rule fired on. Zero on a rule that
	// compiled cleanly is the answer somebody is usually looking for.
	Matched int `json:"matched"`
}

type Set struct {
	Rules []Rule `json:"rules,omitempty"`
	// Disabled is the master switch for the whole list, so somebody can find out
	// whether a rule set is the reason for what they are seeing without deleting
	// it or switching off nine rules one at a time.
	//
	// It is spelled Disabled and not Enabled for the same reason Rule.Disabled is:
	// the zero value has to be a live set. An Enabled field arrives false in every
	// stored settings file written before it existed, which would switch both the
	// Packagizer and the link filter off on the first boot after the upgrade — and
	// the symptom reads as a matching bug, not as a settings bug, so it is looked
	// for in the wrong place.
	Disabled bool `json:"disabled,omitempty"`
	// StopAfterMatch ends evaluation at the first rule that matches. The
	// Packagizer wants it off, so every matching rule contributes and a later
	// rule wins per field; a filter usually wants it on, so an accept placed
	// above a broad reject actually protects the link.
	StopAfterMatch bool `json:"stopAfterMatch,omitempty"`
}

type Variable struct {
	// Tag is inserted verbatim, with N and FIELD left standing as the parts the
	// user replaces.
	Tag string `json:"tag"`
	// ID keys the description the interface shows beside it.
	ID string `json:"id"`
	// Params names the placeholders inside Tag, so the form can prompt for them
	// instead of leaving the user to notice a literal N in their folder name.
	Params []string `json:"params,omitempty"`
}

type Verdict struct {
	Rejected bool   `json:"rejected"`
	Rule     string `json:"rule,omitempty"`
	Reason   string `json:"reason,omitempty"`
}