-
Notifications
You must be signed in to change notification settings - Fork 24
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation Update to clean up and improve documentation for proto …
…message definitions
* Added svg diagrams for most state objects.
* Clean up copyright headers to remove non-printing characters.
* Began reworking documents to produce clear documentation via the most common document processor for protobuf
* There are limitations that encourage a slightly different style.
* Markdown produces the best output (with slight modifications to the template), so that is selected.
* Added a modified markdown template (to work around the "sanitization" bug in the docs processor for markdown).
* Now we can add most HTML tags in the markdown, allowing things like line breaks in attribute descriptions.
* The results are much better, might be something worth submitting as a PR upstream (along with some non-trivial examples)...
* This allows using a line with only `<br/>` or `<p>` in place of blank lines (that break the markdown tables).
* Ideally the go code would do this, but that's a bigger lift, this works for now.
* Thorough update of many proto files in state.
* Committed a fully generated set of docs in this branch for review purposes, will remove before completing the task.
* Moved document outputs to `documents/api/services` to allow for other document sets
* Removed unused imports to quiet warnings.
* Replicate "service" documentation to the message body entries for clarity
* Message bodies were just "see ..." references, which do not link well, and push content specification to the service API, which muddies both.
* Rewrite message body documentation to *content* specification
* Rewrite "service" API documentation to *API* specification.
* Adjust common fields to have consistent descriptions.
Mass update of the copyright header.
* Updated copyright header to match services standard.
* Corrected incorrect copy-paste of older years in state.
* Removed hidden zero-width characters.
* Removed unnecessary additions.
* Adjusted query header and query response header text to be more uniform.
* Thorough update across services proto definitions
* State messages complete
* Consensus service complete
* Smart Contract service complete.
* Crypto Service complete.
* Miscellaneous protos complete.
* File Service complete.
* Freeze Service complete.
* Transaction and records complete.
* Synthetic node_stake_update transaction complete.
* Query and Response complete.
* General Queries complete.
* Harmonized crypto_get_info and get_account_details
* Discovered no service interface defines `getByKey`, we may
be able to completely remove that query, with it's handler
in network admin service, and just reserve the field number
in query and hedera functionality henceforth.
* Found a few more unsupported queries and marked them deprecated in
the query.proto one-of block.
* Network Service complete
* Schedule Service complete
* Token Service complete
* Fixed the new `token_reject` file, which was not created according to
the content in the HIP.
* Utility Service complete.
* Address Book Service complete.
* Minor updates and clarification only.
* HIP 904 additions
* Updated all airdrop and pending airdrop entries.
* Response Code
* Separate due to size (iover 360 fields) and frequent
changes. Will be addressed in a separate PR to minimize
conflict with ongoing services work.
Signed-off-by: Joseph Sinclair <[email protected]>- Loading branch information
1 parent
0047255
commit 243d22f
Showing
286 changed files
with
40,300 additions
and
5,064 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -77,6 +77,7 @@ secring.* | |
|
|
||
| ### Custom items | ||
| .idea | ||
| **/*.iml | ||
| *.sw* | ||
| *.iml | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| // Copyright 2023 Buf Technologies, Inc. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| syntax = "proto3"; | ||
|
|
||
| package buf.validate; | ||
|
|
||
| option go_package = "buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go/buf/validate"; | ||
| option java_multiple_files = true; | ||
| option java_outer_classname = "ExpressionProto"; | ||
| option java_package = "build.buf.validate"; | ||
|
|
||
| // `Constraint` represents a validation rule written in the Common Expression | ||
| // Language (CEL) syntax. Each Constraint includes a unique identifier, an | ||
| // optional error message, and the CEL expression to evaluate. For more | ||
| // information on CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md). | ||
| // | ||
| // ```proto | ||
| // message Foo { | ||
| // option (buf.validate.message).cel = { | ||
| // id: "foo.bar" | ||
| // message: "bar must be greater than 0" | ||
| // expression: "this.bar > 0" | ||
| // }; | ||
| // int32 bar = 1; | ||
| // } | ||
| // ``` | ||
| message Constraint { | ||
| // `id` is a string that serves as a machine-readable name for this Constraint. | ||
| // It should be unique within its scope, which could be either a message or a field. | ||
| string id = 1; | ||
|
|
||
| // `message` is an optional field that provides a human-readable error message | ||
| // for this Constraint when the CEL expression evaluates to false. If a | ||
| // non-empty message is provided, any strings resulting from the CEL | ||
| // expression evaluation are ignored. | ||
| string message = 2; | ||
|
|
||
| // `expression` is the actual CEL expression that will be evaluated for | ||
| // validation. This string must resolve to either a boolean or a string | ||
| // value. If the expression evaluates to false or a non-empty string, the | ||
| // validation is considered failed, and the message is rejected. | ||
| string expression = 3; | ||
| } | ||
|
|
||
| // `Violations` is a collection of `Violation` messages. This message type is returned by | ||
| // protovalidate when a proto message fails to meet the requirements set by the `Constraint` validation rules. | ||
| // Each individual violation is represented by a `Violation` message. | ||
| message Violations { | ||
| // `violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected. | ||
| repeated Violation violations = 1; | ||
| } | ||
|
|
||
| // `Violation` represents a single instance where a validation rule, expressed | ||
| // as a `Constraint`, was not met. It provides information about the field that | ||
| // caused the violation, the specific constraint that wasn't fulfilled, and a | ||
| // human-readable error message. | ||
| // | ||
| // ```json | ||
| // { | ||
| // "fieldPath": "bar", | ||
| // "constraintId": "foo.bar", | ||
| // "message": "bar must be greater than 0" | ||
| // } | ||
| // ``` | ||
| message Violation { | ||
| // `field_path` is a machine-readable identifier that points to the specific field that failed the validation. | ||
| // This could be a nested field, in which case the path will include all the parent fields leading to the actual field that caused the violation. | ||
| string field_path = 1; | ||
|
|
||
| // `constraint_id` is the unique identifier of the `Constraint` that was not fulfilled. | ||
| // This is the same `id` that was specified in the `Constraint` message, allowing easy tracing of which rule was violated. | ||
| string constraint_id = 2; | ||
|
|
||
| // `message` is a human-readable error message that describes the nature of the violation. | ||
| // This can be the default error message from the violated `Constraint`, or it can be a custom message that gives more context about the violation. | ||
| string message = 3; | ||
|
|
||
| // `for_key` indicates whether the violation was caused by a map key, rather than a value. | ||
| bool for_key = 4; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| // Copyright 2023 Buf Technologies, Inc. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| syntax = "proto3"; | ||
|
|
||
| package buf.validate.priv; | ||
|
|
||
| import "google/protobuf/descriptor.proto"; | ||
|
|
||
| option go_package = "buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go/buf/validate/priv"; | ||
| option java_multiple_files = true; | ||
| option java_outer_classname = "PrivateProto"; | ||
| option java_package = "build.buf.validate.priv"; | ||
|
|
||
| extend google.protobuf.FieldOptions { | ||
| // Do not use. Internal to protovalidate library | ||
| optional FieldConstraints field = 1160; | ||
| } | ||
|
|
||
| // Do not use. Internal to protovalidate library | ||
| message FieldConstraints { | ||
| repeated Constraint cel = 1; | ||
| } | ||
|
|
||
| // Do not use. Internal to protovalidate library | ||
| message Constraint { | ||
| string id = 1; | ||
| string message = 2; | ||
| string expression = 3; | ||
| } |
Oops, something went wrong.