sui_rpc_api/read_mask_defaults.rs
1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use sui_rpc::field::FieldMask;
5use sui_rpc::field::FieldMaskTree;
6use sui_rpc::field::FieldMaskUtil;
7use sui_rpc::field::MessageFields;
8use sui_rpc::proto::google::rpc::bad_request::FieldViolation;
9
10use crate::ErrorReason;
11use crate::RpcError;
12
13/// Default read mask for a transaction (`get_transaction`, `list_transactions`).
14pub const TRANSACTION: &str = "digest";
15
16/// Default read mask for a checkpoint (`get_checkpoint`, `list_checkpoints`).
17pub const CHECKPOINT: &str = "sequence_number,digest";
18
19/// Default read mask for an event (`list_events`; there is no `get_events`).
20pub const EVENT: &str = "event_type";
21
22/// Default read mask for an epoch (`get_epoch`; there is no `list_epochs`).
23pub const EPOCH: &str = "epoch,first_checkpoint,last_checkpoint,start,end,reference_gas_price,protocol_config.protocol_version";
24
25/// Default read mask for a protocol config (`get_protocol_config`).
26pub const PROTOCOL_CONFIG: &str = "protocol_version";
27
28/// Default read mask for an object (`get_object`, `list_object_versions`).
29pub const OBJECT: &str = "object_id,version,digest";
30
31/// Default `removal_read_mask` for each removal in an object's version listing
32/// (`list_object_versions`).
33pub const OBJECT_REMOVAL: &str = "version,kind";
34
35/// Default read mask for an owned-object listing (`list_owned_objects`).
36pub const OWNED_OBJECT: &str = "object_id,version,object_type";
37
38/// Default read mask for a dynamic-field listing (`list_dynamic_fields`).
39pub const DYNAMIC_FIELD: &str = "parent,field_id";
40
41/// Default read mask for transaction execution (`ExecuteTransaction`).
42pub const EXECUTE_TRANSACTION: &str = "effects";
43
44/// Validate an optional request `read_mask` against message type `M`, falling
45/// back to `default` when the request omits one, and return it as a
46/// `FieldMaskTree`. Shared by every read-mask-bearing handler (get, list, and
47/// subscribe) so validation and the "no mask -> default" rule stay identical
48/// across them. `default` is an explicit argument because one message type can
49/// carry different per-endpoint defaults (e.g. `ExecutedTransaction` uses
50/// `TRANSACTION` for get/list but `EXECUTE_TRANSACTION` for execution).
51pub fn validate_read_mask<M: MessageFields>(
52 read_mask: Option<FieldMask>,
53 default: &str,
54) -> Result<FieldMaskTree, RpcError> {
55 validate_field_mask::<M>("read_mask", read_mask, default)
56}
57
58/// [`validate_read_mask`] for a mask in request field `field`, which an invalid
59/// path's `FieldViolation` names.
60pub fn validate_field_mask<M: MessageFields>(
61 field: &str,
62 mask: Option<FieldMask>,
63 default: &str,
64) -> Result<FieldMaskTree, RpcError> {
65 let mask = mask.unwrap_or_else(|| FieldMask::from_str(default));
66 mask.validate::<M>().map_err(|path| {
67 FieldViolation::new(field)
68 .with_description(format!("invalid {field} path: {path}"))
69 .with_reason(ErrorReason::FieldInvalid)
70 })?;
71 Ok(FieldMaskTree::from(mask))
72}