Add document for ConnRawEvent

CHANGELOG.md

@@ -27,10 +27,13 @@ Versioning](https://semver.org/spec/v2.0.0.html).
   - Changed `COMPATIBLE_VERSION_REQ` to ">=0.24.0-alpha.1,<0.25.0".
   - Added migration function `migrate_0_23_0_to_0_24_0_op_log`. This function
     performs a migration to change the key and value of `Oplog`.
-- The term timestamp is replaced with the term time, in event structs,where the
+- The term timestamp is replaced with the term time, in event structs, where the
   type is `DateTime<Utc>`. This change impacts GraphQL APIs that return event
   data and filter parameters that used timestamp. Additionally, the JSON file
-  generated by the `export` GraphQL API is also reflects the new name.
+  generated by the `export` GraphQL API also reflects the new name.
+- Documentation of the following GraphQL APIs is updated:
+  - `connRawEvents`
+  - `networkRawEvents`
 
 ## [0.23.0] - 2024-11-21
 

src/graphql/client/schema/schema.graphql

@@ -60,21 +60,69 @@ type Config {
   ackTransmission: Int!
 }
 
+# Represents an event extracted from a session.
 type ConnRawEvent {
+  # Start Time.
   time: DateTime!
+
+  # Source IP address.
   origAddr: String!
+
+  # Source port number.
   origPort: Int!
+
+  # Destination IP address.
   respAddr: String!
+
+  # Destination port number.
   respPort: Int!
+
+  # Protocol number. TCP is 6, UDP is 17.
   proto: Int!
+
+  # Connection state. This is only used in TCP connections.
+  #
+  # The connection state is a string of letters that represent the state of the connection. The
+  # letters are as follows:
+  #
+  # - S: The originator sent a SYN segment.
+  # - h: The responder sent a SYN ACK segment.
+  # - A: The originator sent an ACK segment.
+  # - D: The originator sent at least one segment with payload data. In this case, that was HTTP
+  # over TCP.
+  # - a: The responder replied with an ACK segment.
+  # - d: The responder replied with at least one segment with payload data.
+  # - F: The originator sent a FIN ACK segment.
+  # - f: The responder replied with a FIN ACK segment.
+  # - R: The originator sent a RST segment.
+  # - r: The responder sent a RST segment.
+  # - T: Timeout
+  #
+  # For example, `ShDdAaFf` indicates a session without packet loss.
   connState: String!
+
+  # Duration. It is in nanoseconds.
   duration: StringNumberI64!
+
+  # Service name.
   service: String!
+
+  # Bytes sent by source.
   origBytes: StringNumberU64!
+
+  # Bytes received by destination.
   respBytes: StringNumberU64!
+
+  # Packets sent by source.
   origPkts: StringNumberU64!
+
+  # Packets received by destination.
   respPkts: StringNumberU64!
+
+  # Layer 2 bytes sent by source.
   origL2Bytes: StringNumberU64!
+
+  # Layer 2 bytes received by destination.
   respL2Bytes: StringNumberU64!
 }
 
@@ -1014,12 +1062,6 @@ type OpLogRawEventEdge {
   cursor: String!
 }
 
-input TsvFilter {
-  protocol: String!
-  times: [DateTime!]!
-  sensor: String!
-}
-
 type Packet {
   requestTime: DateTime!
   packetTime: DateTime!
@@ -1991,3 +2033,9 @@ type TlsRawEventEdge {
   # A cursor for use in pagination
   cursor: String!
 }
+
+input TsvFilter {
+  protocol: String!
+  times: [DateTime!]!
+  sensor: String!
+}

src/graphql/network.rs

@@ -126,23 +126,57 @@ impl RawEventFilter for SearchFilter {
     }
 }
 
+/// Represents an event extracted from a session.
 #[derive(SimpleObject, Debug, ConvertGraphQLEdgesNode)]
 #[graphql_client_type(names = [conn_raw_events::ConnRawEventsConnRawEventsEdgesNode, network_raw_events::NetworkRawEventsNetworkRawEventsEdgesNodeOnConnRawEvent])]
 struct ConnRawEvent {
+    /// Start Time.
     time: DateTime<Utc>,
+    /// Source IP address.
     orig_addr: String,
+    /// Source port number.
     orig_port: u16,
+    /// Destination IP address.
     resp_addr: String,
+    /// Destination port number.
     resp_port: u16,
+    /// Protocol number. TCP is 6, UDP is 17.
     proto: u8,
+    /// Connection state. This is only used in TCP connections.
+    ///
+    /// The connection state is a string of letters that represent the state of the connection. The
+    /// letters are as follows:
+    ///
+    /// - S: The originator sent a SYN segment.
+    /// - h: The responder sent a SYN ACK segment.
+    /// - A: The originator sent an ACK segment.
+    /// - D: The originator sent at least one segment with payload data. In this case, that was HTTP
+    ///   over TCP.
+    /// - a: The responder replied with an ACK segment.
+    /// - d: The responder replied with at least one segment with payload data.
+    /// - F: The originator sent a FIN ACK segment.
+    /// - f: The responder replied with a FIN ACK segment.
+    /// - R: The originator sent a RST segment.
+    /// - r: The responder sent a RST segment.
+    /// - T: Timeout
+    ///
+    /// For example, `ShDdAaFf` indicates a session without packet loss.
     conn_state: String,
+    /// Duration. It is in nanoseconds.
     duration: StringNumberI64,
+    /// Service name.
     service: String,
+    /// Bytes sent by source.
     orig_bytes: StringNumberU64,
+    /// Bytes received by destination.
     resp_bytes: StringNumberU64,
+    /// Packets sent by source.
     orig_pkts: StringNumberU64,
+    /// Packets received by destination.
     resp_pkts: StringNumberU64,
+    /// Layer 2 bytes sent by source.
     orig_l2_bytes: StringNumberU64,
+    /// Layer 2 bytes received by destination.
     resp_l2_bytes: StringNumberU64,
 }