Merge pull request #143 from stefan-brus-frequenz/end_time

Update time filter docs, clarify presence/absence of fields

Author: thomas-nicolai-frequenz

RELEASE_NOTES.md

@@ -2,8 +2,7 @@
 
 ## Summary
 
-- The changes introduced in v0.9.0 have been reverted. `frequenz.api.reporting.v1` now serves the `frequenz.api.common.v1` definitions.
-- A new protobuf package has been introduced, `frequenz.api.reporting.v1alpha10`, in which the `frequenz.api.common.v1alpha8` adaptations can be found.
+- The behavior of the TimeFilter has changed, and its documentation has been updated accordingly.
 
 ## Upgrading
 

mkdocs.yml

@@ -112,6 +112,8 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
+            docstring_options:
+              warn_missing_types: false
           import:
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

proto/frequenz/api/reporting/v1alpha10/reporting.proto

@@ -74,26 +74,30 @@ enum FilterOption {
   FILTER_OPTION_INCLUDE = 2;
 }
 
-// Time-based filter for querying aggregated microgrid components data.
+// Time-filter defining the historical window and real-time behaviour of the stream.
 //
-// !!! note
-//     Specifies the start and end time for the query. Both fields are optional, but
-//     their absence or presence has specific implications for the query results.
-//     Data will be returned as a set of rows, which each row containing a timestamp.
-//     This timestamp will be >= start and < end.
+// Semantics:
+//   - If `end_time` is provided, it MUST be ≤ the current server time. The
+//     server streams all samples t where start_time ≤ t < end_time and
+//     then closes the stream.
+//
+//   - If `end_time` is omitted, the server streams all historical samples
+//     t ≥ start_time (if provided) and then continues streaming new samples
+//     in real time. The stream remains open indefinitely.
+//
+//   - If `start_time` is omitted:
+//         – and `end_time` is omitted: the stream produces no historical data
+//           and begins streaming real-time samples only.
+//         – and `end_time` is provided: the historical window is empty and
+//           the stream closes immediately.
+//
+// Validation rules:
+//   - end_time > now() → INVALID_ARGUMENT
 message TimeFilter {
   // Optional UTC start time for the query.
-  //
-  // !!! info
-  //     If not provided, the query defaults to the earliest available data for the
-  //     specified microgrid components.
   google.protobuf.Timestamp start_time = 1;
 
   // Optional UTC end time for the query.
-  //
-  // !!! info
-  //     If not provided, the query will retrieve the requested data and continue
-  //     streaming all new data as it becomes available.
   google.protobuf.Timestamp end_time = 2;
 }