blob: bfcdebe747bd5943ec10b785cc01778ab9bc8005 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
# AGENTS.md
## What this repo is
`phorge-elasticsearch-modern` is a Phorge full-text search extension that replaces the
bundled Elasticsearch 5.x engine with one that speaks the typeless Elasticsearch 7.x/8.x
and OpenSearch REST API. It implements `PhabricatorFulltextStorageEngine` (via
`PhabricatorElasticFulltextStorageEngine`) and is registered as a phutil library that
Phorge loads at runtime.
Current status: **v0.1.0 in active development**. Twelve `task/*` feature PRs are in
flight, all stacked against `development`. The engine passes its 16-unit PhutilTestCase
suite; live smoke tests (V1–V4) against a real Phorge + Elasticsearch cluster are the
next milestone.
Spec + plan: [Confluence page 891322369](https://vyos.atlassian.net/wiki/spaces/VYOS/pages/891322369)
---
## Repository layout
```text
src/
host/
VyOSElasticModernHost.php # PhabricatorClusterSearchHost subclass (final)
engine/
VyOSElasticModernFulltextStorageEngine.php # main engine class (final)
__tests__/
VyOSElasticModernEngineTestCase.php # PhutilTestCase unit tests (16/16)
__phutil_library_init__.php # phutil library registration
__phutil_library_map__.php # phutil symbol map (generated by arc liberate)
README.md
VERIFICATION.md # planned — smoke-test guide
LICENSE
AGENTS.md # this file
.github/
copilot-instructions.md # symlink → ../AGENTS.md
.coderabbit.yaml
.mergify.yml
.arcconfig
```
---
## Working directory and toolchain
| Item | Value |
|------|-------|
| Repo path | `~/GitHub/phorge-elasticsearch-modern/` |
| Parent Phorge clone | `~/GitHub/phorge/` (Phorge HEAD, used for class lookup and smoke tests) |
| PHP | Homebrew `php@8.3` |
| Arcanist | `~/GitHub/arcanist/bin/arc` |
| PATH bootstrap | `/Users/syncer/GitHub/arcanist/bin:/opt/homebrew/opt/php@8.3/bin` |
The local Phorge dev environment (Docker + MySQL) is needed for the V1–V4 smoke tests.
Unit tests (PhutilTestCase only) do **not** require a running Phorge instance.
---
## Branch model
| Branch | Purpose |
|--------|---------|
| `production` | Default branch; stable releases. Plumbing and governance land here directly. |
| `development` | Integration branch; task PRs merge here via the stacked chain. |
| `task/<slug>` | One per PR; stacked against `development`. |
Promotion path: `development` → `production` via a promotion PR after the task stack closes.
---
## Test discipline
```bash
# Run all unit tests (no Phorge daemon or MySQL needed)
arc unit --
```
Test base class: `PhutilTestCase`. Do **not** use `PhabricatorTestCase` — the latter
bootstraps Phorge and requires a running MySQL instance.
Current count: **16/16 passing**.
---
## Lint discipline
```bash
arc lint --
```
Clean except one advisory XHP132 warning (documented inline in the engine class).
---
## PR and review flow
This repo follows the standard VyOS flow from `~/.claude/rules/global/vyos-github.md`:
1. Phase 0 — pre-PR `coderabbit review --base origin/<base-branch> --agent` locally.
2. Phase 1 — draft PR; iterate `@copilot review` until silent.
3. Phase 2 — mark ready-for-review; CodeRabbit auto-reviews on the flip.
4. Adversarial review gate (Codex) fires after CodeRabbit threads are resolved, before merge.
---
## Key design constraints
These are load-bearing decisions baked into the implementation. Do not silently reverse them.
### Class structure
- `VyOSElasticModernFulltextStorageEngine` is **`final`** and lives at
`src/engine/VyOSElasticModernFulltextStorageEngine.php`. Do not extend it; modify it
in place.
- `VyOSElasticModernHost` is **`final`** and lives at `src/host/VyOSElasticModernHost.php`.
- `PhabricatorElasticsearchQueryBuilder` is **`final`** in upstream Phorge — use by
composition (instantiate and call methods), never by subclassing.
### PHP visibility
- **Do NOT redeclare `$service`** as a property in the engine or host class. The parent
`PhabricatorFulltextStorageEngine` declares it `protected`; redeclaring as `private`
in a `final` child class causes a PHP fatal: `Cannot redeclare $service as private`.
### Engine identifier
- The identifier string `'elasticsearch-modern'` is load-bearing. Phorge's
`cluster.search[].type` config key selects the engine by this string. Changing it
requires a coordinated config migration on every deployment.
### Query semantics
- The `exclude` saved-query parameter uses `bool.must_not.ids`, **not** the obsolete
Elasticsearch 5.x `not` filter clause (removed in ES 6+).
- All index operations use the typeless API (`/<index>/_doc/<id>`), not the deprecated
`/<index>/<type>/<id>` form.
### Index lifecycle
- The engine manages a single index per Phorge installation, named via `getIndexName()`.
- `buildSpec()` returns a typeless index settings + mappings body compatible with ES 7+/
OpenSearch.
---
## Notes for future contributors
- The `__phutil_library_map__.php` is generated by `arc liberate .` — do not edit it
manually. Regenerate it whenever a new class is added.
- Smoke tests V1–V4 require a live Phorge + Elasticsearch 7+ cluster. See
`VERIFICATION.md` (planned) for the matrix.
- No `arc diff` / Differential workflow — this repo uses GitHub PRs directly.
- License: Apache 2.0 — see `LICENSE`.
|
