Deployment and lifecycle management for Nix
docs: rename
-120
doc/ideas.org
docs/doc/ideas.org
doc/ideas.org
docs/doc/ideas.org
-120
docs/subscription-rules.md
-120
docs/subscription-rules.md
···
1
-
# Subscription Rules
2
-
3
-
Subscription rules allow agents to filter seeds based on tag values when requesting deployments.
4
-
5
-
## Overview
6
-
7
-
When an agent subscribes to a seed, it can optionally specify rules that filter seeds by their tags. Only seeds matching ALL rules will be selected for deployment.
8
-
9
-
## Agent Configuration
10
-
11
-
Configure subscriptions with rules in your agent config file or `config/runtime.exs`:
12
-
13
-
```elixir
14
-
subscriptions: [
15
-
%{
16
-
seed_name: "myhost",
17
-
seed_type: "nixos",
18
-
rules: [
19
-
%{key: "branch", op: "eq", value: "main"},
20
-
%{key: "repo", op: "eq", value: "https://github.com/example/repo"}
21
-
]
22
-
},
23
-
# Subscription without rules matches any seed with matching name/type
24
-
%{
25
-
seed_name: "myhost",
26
-
seed_type: "home-manager"
27
-
}
28
-
]
29
-
```
30
-
31
-
## Rule Schema
32
-
33
-
Each rule has three fields:
34
-
35
-
- **key** (string): The tag key to match (e.g., "branch", "repo", "environment")
36
-
- **op** (string): The comparison operation. Currently supports:
37
-
- `"eq"` - Equality check
38
-
- **value** (string): The value to match against
39
-
40
-
## Seed Matching Behavior
41
-
42
-
When a deployment is requested for a subscription with rules:
43
-
44
-
1. Filter seeds by `seed_name` and `seed_type`
45
-
2. For each rule, filter seeds that have a matching tag with `key` and `value`
46
-
3. ALL rules must match (AND logic)
47
-
4. Return the latest matching seed (by `inserted_at`)
48
-
49
-
### Examples
50
-
51
-
**Seed 1:**
52
-
```elixir
53
-
%{
54
-
name: "myhost",
55
-
seed_type: "nixos",
56
-
artifact: "/nix/store/abc...",
57
-
tags: [
58
-
%{key: "branch", value: "main"},
59
-
%{key: "repo", value: "https://github.com/example/repo"}
60
-
]
61
-
}
62
-
```
63
-
64
-
**Seed 2:**
65
-
```elixir
66
-
%{
67
-
name: "myhost",
68
-
seed_type: "nixos",
69
-
artifact: "/nix/store/def...",
70
-
tags: [
71
-
%{key: "branch", value: "dev"}
72
-
]
73
-
}
74
-
```
75
-
76
-
**Subscription:**
77
-
```elixir
78
-
%{
79
-
seed_name: "myhost",
80
-
seed_type: "nixos",
81
-
rules: [
82
-
%{key: "branch", op: "eq", value: "main"}
83
-
]
84
-
}
85
-
```
86
-
87
-
**Result:** Seed 1 matches (has branch=main). Seed 2 does not match (has branch=dev).
88
-
89
-
## Creating Seeds with Tags
90
-
91
-
When submitting seeds via CLI or API, include tags:
92
-
93
-
```bash
94
-
# CLI (not yet implemented - placeholder)
95
-
sower seed submit --name myhost --type nixos \
96
-
--artifact /nix/store/... \
97
-
--tag branch=main \
98
-
--tag repo=https://github.com/example/repo
99
-
```
100
-
101
-
Server-side Elixir:
102
-
```elixir
103
-
Sower.Seed.create(%{
104
-
name: "myhost",
105
-
seed_type: "nixos",
106
-
artifact: "/nix/store/...",
107
-
tags: [
108
-
%{key: "branch", value: "main"},
109
-
%{key: "repo", value: "https://github.com/example/repo"}
110
-
]
111
-
})
112
-
```
113
-
114
-
## Future Enhancements
115
-
116
-
Potential future rule operators:
117
-
- `ne` - Not equal
118
-
- `in` - Value in list
119
-
- `regex` - Regular expression match
120
-
- `gt`, `lt` - Greater/less than (for version comparisons)