Struct GroupDef 

pub struct GroupDef {
    pub id: String,
    pub description: Option<String>,
    pub members: Vec<String>,
    pub query: Option<String>,
    pub refresh: Option<String>,
    pub tags: Vec<String>,
    pub origin: Option<RepoOrigin>,
}

A declared fleet group (#1032): the third manifest kind alongside Manifest (jobs) and Schedule (schedules), stored in BUCKET_GROUP_DEFS keyed by id.

(The first doc line deliberately does not start with #NNN — schemars treats a leading # as a Markdown heading and would extract it as the schema title, garbling it. Same reason View’s doc leads with prose.)

A group definition names a set of PCs in one of two mutually-exclusive ways:

• static — a literal members list. Declared, git-reviewable membership (the auditability win over hand-editing the imperative agent_groups KV).
• dynamic — a read-only SQL query that returns a pc_id column. Membership is derived from the fleet’s own facts (agents, inventory_facts + json_extract(facts_json, …), feeds, check_status, explode: tables — anything in the projector DB), so “every client OS”, “the servers sharing a hostname prefix”, “machines still on build 26100” are all just a SELECT. The query runs in the backend read-only sandbox (api::query), never on the endpoint.

A schedule’s target.groups resolves a defined group (static or dynamic) in addition to the imperative agent_groups membership, so declared groups and manually-assigned ones coexist and this never mutates agent_groups.

Fields

id: String

Stable identifier (the KV key + URL segment + the name a schedule’s target.groups references). Required; same [A-Za-z0-9._-] charset as a View id via is_valid_resource_id.

description: Option<String>

Optional human description shown on the groups admin page.

members: Vec<String>

Static membership — a literal list of pc_ids. Mutually exclusive with query; exactly one of the two must be set (enforced by GroupDef::validate).

query: Option<String>

Dynamic membership — a read-only SELECT/WITH returning a pc_id column. Mutually exclusive with members. The backend validates it read-only at group create and again at run time; a write verb / stacked statement is rejected. Empty string is treated as unset so an operator can comment the body out to switch to members: without dropping the key.

refresh: Option<String>

Membership-recompute cadence for a dynamic group as a humantime duration ("30m", "6h"). Absent ⇒ DEFAULT_GROUP_REFRESH. Ignored for a static group.

tags: Vec<String>

Free-form operator taxonomy (same role as Manifest::tags).

origin: Option<RepoOrigin>

GitOps provenance (#678), stamped by kanade group def create from the source YAML’s Git context — same as View::origin.

Implementations

impl GroupDef

pub fn dynamic_query(&self) -> Option<&str>

The dynamic SQL body if this is a dynamic group — a non-blank query. (An empty-string query reads as unset, mirroring Execute::script.)

pub fn refresh_interval(&self) -> Duration

The effective recompute cadence for a dynamic group — the parsed refresh or DEFAULT_GROUP_REFRESH. Falls back to the default on an unparseable value rather than panicking on the read path (validation already rejected a bad value at create time).

pub fn validate(&self) -> Result<(), String>

Trait Implementations

impl Clone for GroupDef

fn clone(&self) -> GroupDef

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GroupDef

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for GroupDef

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for GroupDef

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for GroupDef

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StrictSchema for GroupDef

GroupDef likewise has no flattened field.

fn strict_top_level_keys() -> Option<&'static [&'static str]>

The complete set of valid top-level keys, or None when the type has no flattened field. See the trait docs.