| // Copyright 2022 The LUCI Authors. |
| // |
| // 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. |
| |
| // Package protowalk contains routines for efficiently walking proto messages, |
| // focusing on the ability to react to field annotations. |
| // |
| // This package defines an interface (FieldProcessor) which you can |
| // implement to react to any fields you like. |
| // |
| // This package also comes with stock implementations for the following common |
| // field annotations: |
| // - google.api.field_behavior = REQUIRED |
| // - google.api.field_behavior = OUTPUT_ONLY |
| // - deprecated = true |
| // |
| // # How it works |
| // |
| // 1. Register a FieldProcessor using RegisterFieldProcessor. |
| // |
| // A FieldProcessor checks and/or manipulates fields in a proto message. When |
| // registering an implementation, you also provide a `selector` function which |
| // detects fields (e.g. by their type, field options, etc.) that the |
| // FieldProcessor wants to operate on. |
| // |
| // 2. Use the Fields() with one or more FieldProcessor instantances to process |
| // a proto message. |
| // |
| // Fields generates, once per process, a global cache entry keyed on |
| // (msgType, processorType). This entry is a list of fields in `msgType` |
| // which the FieldProcessor's registered `selector` function says it should |
| // operate on, and also indicates for a given field if it should be recursed |
| // for this processor (i.e. if field `M.a` is a message type `A` which has |
| // fields that match this processor). |
| // |
| // Once the cache entries are generated, Fields then generates a 'plan' which is |
| // the combination of _all_ the provided processors' cache entries, such that |
| // Fields() can then walk through all affected fields, once, in order, |
| // generating results from the provided message in an ordered and deterministic |
| // fashion. |
| // |
| // The upshot is that Fields() should be O(CheckableFields), no matter how big |
| // the proto messages are, rather than a naive O(Fields) implementation. |
| // |
| // A Result contains the ProtoPath and a message generated by the |
| // FieldProcessor. The ProtoPath describes the path through the source message |
| // to the affected field, and can either be printed for display, or can be used |
| // to retrieve the actual value. |
| package protowalk |
