diff --git a/ZB.MOM.WW.GalaxyRepository/src/ZB.MOM.WW.GalaxyRepository/Protos/galaxy_repository.proto b/ZB.MOM.WW.GalaxyRepository/src/ZB.MOM.WW.GalaxyRepository/Protos/galaxy_repository.proto new file mode 100644 index 0000000..f36331a --- /dev/null +++ b/ZB.MOM.WW.GalaxyRepository/src/ZB.MOM.WW.GalaxyRepository/Protos/galaxy_repository.proto @@ -0,0 +1,190 @@ +syntax = "proto3"; + +package galaxy_repository.v1; + +option csharp_namespace = "ZB.MOM.WW.GalaxyRepository.Grpc"; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; + +// Wire-compatibility policy (ProtobufStyleGuide): this contract evolves +// additively only. Never renumber or repurpose an existing field number or +// enum value. When a field or enum value is removed, add a `reserved` range +// (and `reserved` name) covering it in the same change so a future editor +// cannot accidentally reuse the retired tag. There are no `reserved` +// declarations today because no field or enum value has ever been removed. + +// Read-only browse over the AVEVA System Platform Galaxy Repository (ZB SQL +// database). Lets clients enumerate the deployed object hierarchy and each +// object's dynamic attributes so they know what tag references to subscribe +// to via the MxAccessGateway service. +service GalaxyRepository { + rpc TestConnection(TestConnectionRequest) returns (TestConnectionReply); + rpc GetLastDeployTime(GetLastDeployTimeRequest) returns (GetLastDeployTimeReply); + rpc DiscoverHierarchy(DiscoverHierarchyRequest) returns (DiscoverHierarchyReply); + + // Server-stream of deploy events. The server emits the current state immediately + // on subscribe (so clients can bootstrap their cache without waiting for the next + // deploy), then emits one event each time the gateway's hierarchy cache observes + // a new galaxy.time_of_last_deploy. The sequence field is monotonically + // increasing per server start; gaps indicate the per-subscriber buffer dropped + // older events because the client was too slow. + rpc WatchDeployEvents(WatchDeployEventsRequest) returns (stream DeployEvent); + + // Returns the direct children of a parent object (or the root objects when + // `parent` is unset). Designed for OPC UA-style lazy expand: clients walk + // one level at a time instead of paging the full hierarchy. Filters mirror + // DiscoverHierarchy exactly. Backed by the same shared hierarchy cache. + rpc BrowseChildren(BrowseChildrenRequest) returns (BrowseChildrenReply); +} + +message TestConnectionRequest {} + +message TestConnectionReply { + bool ok = 1; +} + +message GetLastDeployTimeRequest {} + +message GetLastDeployTimeReply { + bool present = 1; + google.protobuf.Timestamp time_of_last_deploy = 2; +} + +message DiscoverHierarchyRequest { + // Maximum number of objects to return. The server applies its default when + // unset and rejects non-positive values. + int32 page_size = 1; + // Opaque token returned by a previous DiscoverHierarchy response. + string page_token = 2; + // Optional. When set, return only this object and its descendants. + // Empty = full hierarchy. + oneof root { + int32 root_gobject_id = 3; + string root_tag_name = 4; + string root_contained_path = 5; + } + // Optional. Cap on descendant depth from root. Zero returns only the root. + // Unset means unlimited depth. + google.protobuf.Int32Value max_depth = 6; + // Optional object category id filters. + repeated int32 category_ids = 7; + // Optional case-insensitive substring filters against template names. + repeated string template_chain_contains = 8; + // Optional anchored, case-insensitive glob over object tag_name. + string tag_name_glob = 9; + // Optional. Unset or true includes attributes. False returns object skeletons. + optional bool include_attributes = 10; + // Optional. Return only objects with at least one alarm-bearing attribute. + bool alarm_bearing_only = 11; + // Optional. Return only objects with at least one historized attribute. + bool historized_only = 12; +} + +message DiscoverHierarchyReply { + repeated GalaxyObject objects = 1; + // Non-empty when another page is available. + string next_page_token = 2; + // Total number of objects in the cached hierarchy at the time of the call. + int32 total_object_count = 3; +} + +message WatchDeployEventsRequest { + // Optional. When set, the bootstrap event is suppressed if the cached deploy + // time matches this value. Future events are still emitted normally. + google.protobuf.Timestamp last_seen_deploy_time = 1; +} + +message DeployEvent { + // Monotonically increasing per server start. Gaps indicate dropped events. + uint64 sequence = 1; + // Server wall-clock when the cache observed the deploy. + google.protobuf.Timestamp observed_at = 2; + // Galaxy.time_of_last_deploy. Absent only when the Galaxy table reports null. + google.protobuf.Timestamp time_of_last_deploy = 3; + bool time_of_last_deploy_present = 4; + int32 object_count = 5; + int32 attribute_count = 6; +} + +message GalaxyObject { + int32 gobject_id = 1; + string tag_name = 2; + string contained_name = 3; + string browse_name = 4; + int32 parent_gobject_id = 5; + bool is_area = 6; + int32 category_id = 7; + int32 hosted_by_gobject_id = 8; + repeated string template_chain = 9; + repeated GalaxyAttribute attributes = 10; +} + +message GalaxyAttribute { + string attribute_name = 1; + string full_tag_reference = 2; + // Raw Galaxy SQL `dbo.data_type` identifier, passed through unchanged. + // This is NOT a member of `mxaccess_gateway.v1.MxDataType` — Galaxy's + // type enumeration is distinct from MXAccess's wire data-type enum and + // the two must not be cast or compared. The GalaxyRepository service is + // metadata-only and deliberately does not share types with + // mxaccess_gateway.proto. See docs/GalaxyRepository.md. + int32 mx_data_type = 3; + // Human-readable name from Galaxy's `dbo.data_type` table (e.g. "Float", + // "Integer", "Boolean"). Free-form Galaxy text; not a stable enum. + string data_type_name = 4; + bool is_array = 5; + int32 array_dimension = 6; + bool array_dimension_present = 7; + // Raw Galaxy SQL attribute-category identifier, passed through unchanged. + // Galaxy-specific; not mapped to any gateway enum. See + // docs/GalaxyRepository.md. + int32 mx_attribute_category = 8; + // Raw Galaxy SQL security-classification identifier, passed through + // unchanged. Galaxy-specific; not mapped to any gateway enum. See + // docs/GalaxyRepository.md. + int32 security_classification = 9; + bool is_historized = 10; + bool is_alarm = 11; +} + +message BrowseChildrenRequest { + // Parent selector. Empty oneof returns root objects (parent_gobject_id == 0). + oneof parent { + int32 parent_gobject_id = 1; + string parent_tag_name = 2; + string parent_contained_path = 3; + } + + // Maximum number of direct children to return. Server default 500; cap 5000. + int32 page_size = 4; + // Opaque token returned by a previous BrowseChildren response. Bound to the + // cache sequence, parent selector, and the filter set; a mismatch returns + // InvalidArgument. + string page_token = 5; + + // --- Filter parity with DiscoverHierarchy. AND-combined. --- + repeated int32 category_ids = 6; + repeated string template_chain_contains = 7; + string tag_name_glob = 8; + optional bool include_attributes = 9; + bool alarm_bearing_only = 10; + bool historized_only = 11; +} + +message BrowseChildrenReply { + // Direct children matching the filter, sorted areas-first then by + // case-insensitive display name (same order as the dashboard tree). + repeated GalaxyObject children = 1; + // Non-empty when another page of siblings is available. + string next_page_token = 2; + // Total matching direct children of the parent (post-filter). + int32 total_child_count = 3; + // Parallel array, indexed with `children`. True when the child has at least + // one matching descendant under the same filter set. Lets a UI choose + // whether to draw an expand triangle without an extra round trip. + repeated bool child_has_children = 4; + // Cache sequence this reply was projected from. Clients may pass it back as + // part of the page_token contract. Mismatch on the next page -> InvalidArgument. + uint64 cache_sequence = 5; +}