ruleset

README

internal/ruleset

JSON parser and semantic validator for AWS GameLift FlexMatch rule sets.

Responsibility

Turn a []byte containing the FlexMatch rule set JSON document — the same payload accepted by AWS's CreateMatchmakingRuleSet API (RuleSetBody) — into a typed *RuleSet and return descriptive errors for anything that is malformed or contradictory.

This package only describes the rule set; it does not evaluate any rules. The evaluator packages (expr, rule, algorithm, expansion) consume the structures defined here.

Contents

• RuleSet, Team, PlayerAttribute, Algorithm, Rule, CompoundStatement, Expansion, ExpansionStep — the parsed structures that mirror the FlexMatch JSON schema. RuleSet also carries the top-level AcceptanceRequired / AcceptanceTimeoutSeconds fields that drive the player-acceptance flow in the public package.
• RuleType and its constants (RuleComparison, RuleDistance, …, RuleCompound) for switching on rule kind.
• Parse(body []byte) (*RuleSet, error) — entry point. Returns errors that wrap ErrInvalidRuleSet.
• (*RuleSet).Validate() — the semantic checks Parse runs after JSON decoding (uniqueness, references, enum values, expansion target shape, etc.). Exposed for tests and for callers that build a RuleSet by hand.

Design notes

• Fields whose value type varies across rule kinds (most notably referenceValue) are kept as json.RawMessage. Each rule evaluator decodes the raw bytes when it knows the expected shape.
• Optional numeric fields are pointer types (*float64, *int) so the validator and evaluators can distinguish "absent" from "zero".
• Unknown JSON fields are silently ignored on purpose — AWS may add new optional fields and we don't want a strict decoder to reject them.
• Compound rule references are validated against the set of rule names in a second pass, so forward references work.

Documentation

Overview

Package ruleset parses and validates AWS GameLift FlexMatch rule set JSON documents (the same payload accepted by CreateMatchmakingRuleSet).

Index

• Variables
• type Algorithm
• type CompoundStatement
• type Expansion
• type ExpansionStep
• type PlayerAttribute
• type Rule
• type RuleSet
  • func Parse(body []byte) (*RuleSet, error)
  • func (rs *RuleSet) Validate() error
• type RuleType
• type Team

Variables

var ErrInvalidRuleSet = errors.New("flexi: invalid rule set")

ErrInvalidRuleSet is returned when the rule set JSON is malformed or fails semantic validation.

Types

type Algorithm

type Algorithm struct {
	Strategy           string `json:"strategy,omitempty"`
	BatchingPreference string `json:"batchingPreference,omitempty"`
	BalancedAttribute  string `json:"balancedAttribute,omitempty"`
	BackfillPriority   string `json:"backfillPriority,omitempty"`
}

Algorithm captures the rule set's algorithm block.

type CompoundStatement

type CompoundStatement struct {
	Condition string   `json:"condition"`
	Rules     []string `json:"rules"`
}

CompoundStatement is the body of a compound rule: a condition combinator applied to a list of child rule names.

type Expansion

type Expansion struct {
	Target string          `json:"target"`
	Steps  []ExpansionStep `json:"steps"`
}

Expansion declares a time-driven loosening of a target value.

type ExpansionStep

type ExpansionStep struct {
	WaitTimeSeconds int             `json:"waitTimeSeconds"`
	Value           json.RawMessage `json:"value"`
}

ExpansionStep applies Value once WaitTimeSeconds have elapsed.

type PlayerAttribute

type PlayerAttribute struct {
	Name    string          `json:"name"`
	Type    string          `json:"type"`
	Default json.RawMessage `json:"default,omitempty"`
}

PlayerAttribute declares a player attribute the rule set will reference.

type Rule

type Rule struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Type        RuleType `json:"type"`

	// comparison / distance / collection
	Measurements   []string        `json:"measurements,omitempty"`
	ReferenceValue json.RawMessage `json:"referenceValue,omitempty"`

	// comparison
	Operation string `json:"operation,omitempty"`

	// distance
	MaxDistance *float64 `json:"maxDistance,omitempty"`
	MinDistance *float64 `json:"minDistance,omitempty"`

	// absoluteSort
	SortDirection string `json:"sortDirection,omitempty"`
	SortAttribute string `json:"sortAttribute,omitempty"`
	MapKey        string `json:"mapKey,omitempty"`
	SortReference string `json:"sortReference,omitempty"`

	// batchDistance
	BatchAttribute       string   `json:"batchAttribute,omitempty"`
	MaxAttributeDistance *float64 `json:"maxAttributeDistance,omitempty"`
	PartyAggregation     string   `json:"partyAggregation,omitempty"`

	// collection
	MinCount *int `json:"minCount,omitempty"`
	MaxCount *int `json:"maxCount,omitempty"`

	// latency
	MaxLatency *int `json:"maxLatency,omitempty"`

	// compound
	Statement *CompoundStatement `json:"statement,omitempty"`
}

Rule is a single rule entry. Fields not relevant to the rule's Type are zero. referenceValue may be a literal number/string OR a property expression string, hence kept as RawMessage to preserve fidelity until evaluation.

type RuleSet

type RuleSet struct {
	Name                string            `json:"name"`
	RuleLanguageVersion string            `json:"ruleLanguageVersion"`
	PlayerAttributes    []PlayerAttribute `json:"playerAttributes,omitempty"`
	Algorithm           Algorithm         `json:"algorithm"`
	Teams               []Team            `json:"teams"`
	Rules               []Rule            `json:"rules,omitempty"`
	Expansions          []Expansion       `json:"expansions,omitempty"`

	// AcceptanceRequired, when true, holds matches formed by the engine in
	// REQUIRES_ACCEPTANCE state until every player on every matched ticket
	// has accepted via Matchmaker.Accept. Mirrors the FlexMatch field of the
	// same name on MatchmakingConfiguration.
	AcceptanceRequired bool `json:"acceptanceRequired,omitempty"`

	// AcceptanceTimeoutSeconds bounds how long a proposed match may sit in
	// REQUIRES_ACCEPTANCE. When the deadline passes without full acceptance,
	// the proposal is discarded and involved tickets move to TIMED_OUT.
	// Zero means no timeout. Ignored when AcceptanceRequired is false.
	AcceptanceTimeoutSeconds int `json:"acceptanceTimeoutSeconds,omitempty"`
}

RuleSet is the parsed top-level FlexMatch rule set.

func Parse

func Parse(body []byte) (*RuleSet, error)

Parse parses a FlexMatch rule set JSON document and validates it.

func (*RuleSet) Validate

func (rs *RuleSet) Validate() error

Validate performs semantic checks beyond JSON well-formedness.

type RuleType

type RuleType string

RuleType enumerates the FlexMatch rule kinds.

const (
	RuleComparison    RuleType = "comparison"
	RuleDistance      RuleType = "distance"
	RuleAbsoluteSort  RuleType = "absoluteSort"
	RuleBatchDistance RuleType = "batchDistance"
	RuleCollection    RuleType = "collection"
	RuleLatency       RuleType = "latency"
	RuleCompound      RuleType = "compound"
)

type Team

type Team struct {
	Name       string `json:"name"`
	MinPlayers int    `json:"minPlayers"`
	MaxPlayers int    `json:"maxPlayers"`
	Quantity   int    `json:"quantity,omitempty"`
}

Team describes one team slot. Quantity > 1 means the team is created multiple times in a single match.