dohertj2/mxaccessgw
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

DiscoverHierarchy: subtree root + server-side filters #102

New Issue
Closed
opened 2026-04-29 12:51:12 -04:00 by dohertj2 · 2 comments
dohertj2 commented 2026-04-29 12:51:12 -04:00
Owner
Copy Link
Copy Source

Motivation

galaxy_repository.v1.DiscoverHierarchy today returns the entire deployed Galaxy as one paged stream. Every consumer that only cares about a slice (a single Area, only $WinPlatform runtime hosts, only alarm-bearing or historized attributes, a tag-name pattern for an Admin UI search box) has to pull the whole hierarchy and filter client-side.

For a 50k-object Galaxy this is wasteful for first-load and for any UI that does narrow lookups, and it makes future per-key scoped permissions (#follow-up) harder to implement because the server has no concept of "this caller's view of the hierarchy."

The gateway already materializes the full object list inside GalaxyHierarchyCache once per deploy, so server-side slicing is cheap — Where/Skip/Take over an in-memory list.

Proposed proto change

message DiscoverHierarchyRequest {
  int32 page_size = 1;
  string page_token = 2;

  // Optional. When set, return only this object and its descendants.
  // Empty = full hierarchy (current behavior).
  oneof root {
    int32 root_gobject_id = 3;
    string root_tag_name = 4;
    string root_contained_path = 5;  // e.g. "Area1/Line3"
  }

  // Optional. Cap on descendant depth from root.
  // 0 = root only, unset = unlimited.
  google.protobuf.Int32Value max_depth = 6;

  // Optional server-side filters applied against the cached list.
  repeated int32 category_ids = 7;              // e.g. only $WinPlatform/$AppEngine
  repeated string template_chain_contains = 8;  // template-name substring match
  string tag_name_glob = 9;                     // glob, e.g. "Line3_*"
  bool include_attributes = 10;                 // default true; false = skeleton only
  bool alarm_bearing_only = 11;                 // is_alarm == true on >=1 attribute
  bool historized_only = 12;                    // is_historized == true on >=1 attribute
}

Field numbers 3-12 are additive; existing clients keep working unchanged.

Server behavior

  • All filters apply server-side over the cached materialized list. No new SQL.
  • root_* resolves to a gobject_id; missing root returns NotFound.
  • Combination semantics: filters AND together. Empty/unset = no constraint.
  • max_depth is computed against the resolved root, not the Galaxy root.
  • tag_name_glob uses standard */? glob, anchored, case-insensitive.
  • include_attributes=false returns GalaxyObject skeletons with empty attributes — useful for Admin UI tree lazy-load.
  • Paging applies after filtering; total_object_count reflects post-filter count.
  • Existing call (no oneof, no filters) returns the full hierarchy as today.

Acceptance

  • Proto fields added with the numbers above.
  • Server-side filtering implemented in the cache projection layer (no SQL changes).
  • total_object_count is post-filter.
  • Round-trip tests for: full hierarchy (regression), subtree by gobject_id, subtree by tag_name, subtree by contained_path, max_depth cap, each filter individually, all filters combined, paging across a filtered result.
  • Cross-language client smoke matrix updated.
  • .NET client GalaxyRepositoryClient exposes a typed DiscoverHierarchyAsync(DiscoverHierarchyOptions) overload covering the new fields. The current zero-arg DiscoverHierarchyAsync() keeps current behavior.
  • docs/GalaxyRepository.md documents subtree + filter semantics.

Out of scope

Per-API-key constraint scoping (e.g. "this key may only see Area1/*") is a separate feature — see the per-key scoping issue. This issue ships the mechanism; that issue plugs key-bound constraints into the same code path.

Source

Surfaced during lmxopcua Galaxy → MxGateway migration planning (see lmx_mxgw_impl.md audit). OtOpcUa itself doesn't need this for the v1 migration since it pulls the whole hierarchy at startup, but it unblocks Admin UI use cases and is a structural prerequisite for per-key scoping.

## Motivation `galaxy_repository.v1.DiscoverHierarchy` today returns the entire deployed Galaxy as one paged stream. Every consumer that only cares about a slice (a single Area, only `$WinPlatform` runtime hosts, only alarm-bearing or historized attributes, a tag-name pattern for an Admin UI search box) has to pull the whole hierarchy and filter client-side. For a 50k-object Galaxy this is wasteful for first-load and for any UI that does narrow lookups, and it makes future per-key scoped permissions (#follow-up) harder to implement because the server has no concept of "this caller's view of the hierarchy." The gateway already materializes the full object list inside `GalaxyHierarchyCache` once per deploy, so server-side slicing is cheap — `Where`/`Skip`/`Take` over an in-memory list. ## Proposed proto change ```proto message DiscoverHierarchyRequest { int32 page_size = 1; string page_token = 2; // Optional. When set, return only this object and its descendants. // Empty = full hierarchy (current behavior). oneof root { int32 root_gobject_id = 3; string root_tag_name = 4; string root_contained_path = 5; // e.g. "Area1/Line3" } // Optional. Cap on descendant depth from root. // 0 = root only, unset = unlimited. google.protobuf.Int32Value max_depth = 6; // Optional server-side filters applied against the cached list. repeated int32 category_ids = 7; // e.g. only $WinPlatform/$AppEngine repeated string template_chain_contains = 8; // template-name substring match string tag_name_glob = 9; // glob, e.g. "Line3_*" bool include_attributes = 10; // default true; false = skeleton only bool alarm_bearing_only = 11; // is_alarm == true on >=1 attribute bool historized_only = 12; // is_historized == true on >=1 attribute } ``` Field numbers 3-12 are additive; existing clients keep working unchanged. ## Server behavior - All filters apply server-side over the cached materialized list. No new SQL. - `root_*` resolves to a `gobject_id`; missing root returns `NotFound`. - Combination semantics: filters AND together. Empty/unset = no constraint. - `max_depth` is computed against the resolved root, not the Galaxy root. - `tag_name_glob` uses standard `*`/`?` glob, anchored, case-insensitive. - `include_attributes=false` returns `GalaxyObject` skeletons with empty `attributes` — useful for Admin UI tree lazy-load. - Paging applies after filtering; `total_object_count` reflects post-filter count. - Existing call (no oneof, no filters) returns the full hierarchy as today. ## Acceptance - [ ] Proto fields added with the numbers above. - [ ] Server-side filtering implemented in the cache projection layer (no SQL changes). - [ ] `total_object_count` is post-filter. - [ ] Round-trip tests for: full hierarchy (regression), subtree by `gobject_id`, subtree by `tag_name`, subtree by `contained_path`, `max_depth` cap, each filter individually, all filters combined, paging across a filtered result. - [ ] Cross-language client smoke matrix updated. - [ ] `.NET` client `GalaxyRepositoryClient` exposes a typed `DiscoverHierarchyAsync(DiscoverHierarchyOptions)` overload covering the new fields. The current zero-arg `DiscoverHierarchyAsync()` keeps current behavior. - [ ] `docs/GalaxyRepository.md` documents subtree + filter semantics. ## Out of scope Per-API-key constraint scoping (e.g. "this key may only see `Area1/*`") is a separate feature — see the per-key scoping issue. This issue ships the *mechanism*; that issue plugs key-bound constraints into the same code path. ## Source Surfaced during `lmxopcua` Galaxy → MxGateway migration planning (see `lmx_mxgw_impl.md` audit). OtOpcUa itself doesn't need this for the v1 migration since it pulls the whole hierarchy at startup, but it unblocks Admin UI use cases and is a structural prerequisite for per-key scoping.
dohertj2 added the area:contractsarea:gatewaytype:featurepriority:p2 labels 2026-04-29 12:51:12 -04:00
dohertj2 commented 2026-04-29 12:55:54 -04:00
Author
Owner
Copy Link
Copy Source

Companion: #103 (per-key scoped permissions). The browse_subtrees constraint there reuses the filtering pipeline added by this issue.

Companion: #103 (per-key scoped permissions). The `browse_subtrees` constraint there reuses the filtering pipeline added by this issue.
dohertj2 commented 2026-04-29 13:54:17 -04:00
Author
Owner
Copy Link
Copy Source

Implemented in b995c17 (codex/fix-runtime-review-findings).

Verification passed:

  • dotnet build src\MxGateway.Contracts\MxGateway.Contracts.csproj
  • scripts\publish-client-proto-inputs.ps1
  • clients\go\generate-proto.ps1
  • clients\python\generate-proto.ps1
  • gradle :mxgateway-client:generateProto
  • dotnet test src\MxGateway.sln --no-restore
  • dotnet test clients\dotnet\MxGateway.Client.sln --no-restore
  • go test ./...
  • python -m pytest
  • cargo fmt --all --check
  • cargo test --workspace
  • gradle test
  • git diff --check
Implemented in b995c17 (`codex/fix-runtime-review-findings`). Verification passed: - `dotnet build src\MxGateway.Contracts\MxGateway.Contracts.csproj` - `scripts\publish-client-proto-inputs.ps1` - `clients\go\generate-proto.ps1` - `clients\python\generate-proto.ps1` - `gradle :mxgateway-client:generateProto` - `dotnet test src\MxGateway.sln --no-restore` - `dotnet test clients\dotnet\MxGateway.Client.sln --no-restore` - `go test ./...` - `python -m pytest` - `cargo fmt --all --check` - `cargo test --workspace` - `gradle test` - `git diff --check`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:auth
Authentication and authorization
 area:client-dotnet
.NET client library
 area:client-go
Go client library
 area:client-java
Java client library
 area:client-python
Python client library
 area:client-rust
Rust client library
 area:contracts
Protocol and generated contract work
 area:dashboard
Blazor dashboard work
 area:docs
Documentation
 area:gateway
Gateway server work
 area:tests
Automated and live tests
 area:worker
MXAccess worker process work
 blocked
Blocked by dependency
 priority:p0
Must-have / blocking
 priority:p1
High priority
 priority:p2
Normal priority
 type:docs
Documentation work
 type:feature
Feature implementation
 type:infra
Infrastructure and scaffolding
 type:test
Test work
No Label area:contracts area:gateway priority:p2 type:feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dohertj2 (dohertj2)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dohertj2/mxaccessgw#102
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?