| /* |
| * Copyright 2014 The Kythe Authors. All rights reserved. |
| * |
| * 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 kythe.proto; |
| |
| option go_package = "kythe.io/kythe/proto/storage_go_proto"; |
| option java_package = "com.google.devtools.kythe.proto"; |
| |
| // VName is a proto representation of a vector name. |
| // See also |
| // https://kythe.io/docs/kythe-storage.html#_a_id_termvname_a_vector_name_strong_vname_strong |
| // |
| // Rules: |
| // - All fields must be optional, and must have default values. |
| // - No field may ever be removed. If a field is deprecated, it may be |
| // renamed or marked with a comment, but must not be deleted. |
| // - New fields are always added to the end of the message. |
| // - All fields must be strings, not messages. |
| // |
| // One of the key principles is that we want as few fields as possible in a |
| // vname. We're not trying to exhaust the possible dimensions along which a |
| // name could vary, but to find a minimal basis. Be conservative. |
| message VName { |
| // A language-specific signature assigned by the analyzer. |
| // e.g., "com.google.common.collect.Lists.newLinkedList<#1>()" |
| string signature = 1; |
| |
| // The corpus this name belongs to. |
| // e.g., "kythe", "chromium", "github.com/creachadair/imath", "aosp" |
| // The corpus label "kythe" is reserved for internal use. |
| string corpus = 2; |
| |
| // A corpus-specific root label, designating a subordinate collection within |
| // the corpus. If a corpus stores files in unrelated directory structures, |
| // for example, the root can be used to distinguish them. Or, if a corpus |
| // incorporates subprojects, the root can be a project ID that it governs. |
| // This may also be used to distinguish virtual subgroups of a corpus such as |
| // generated files. |
| string root = 3; |
| |
| // A path-structured label describing the location of this object relative to |
| // the corpus and the root. For code, this will generally be the relative |
| // path to the file containing the code, e.g., "storage/service.go" in kythe. |
| // The individual elements of the path are separated by "/". |
| // The path must not start with "/". |
| // The path must be normalized to a canonical form (with no path |
| // elements "", ".", or ".."). |
| // |
| // However, this need not be a true file path; virtual objects like figments |
| // can assign an ad-hoc abstract ID, or omit it entirely. |
| // |
| // Examples: |
| // "devools/kythe/platform/go/datastore.go" (a file) |
| // "type/cpp/void.cc" (a type figment) |
| string path = 4; |
| |
| // The language this name belongs to. |
| // e.g., "c++", "python", "elisp", "haskell", "java" |
| // |
| // The schema will define specific labels for each supported language, so we |
| // don't wind up with a confusion of names like "cxx", "cpp", "C++", etc. |
| // Prototype: Official language name converted to lowercase. If a version |
| // number is necessary, include it, e.g., "python3". |
| string language = 5; |
| |
| // Other fields we may need in the future, but do not currently use: |
| // branch -- a branch name within the corpus depot, e.g., "gslb_branch". |
| // client -- a source-control client ID, e.g., "sergey:googlex:8:citc". |
| |
| // Note: We have intentionally NOT included a revision or timestamp here. |
| // Time should be recorded as facts belonging to the appropriate Nodes and |
| // Edges. Having records of when something existed may be important, but time |
| // is not a good axis for a name -- a name should say "what" something is, not |
| // "when". So we will store timestamps, revisions, and other markers of this |
| // kind as facts inside the graph. |
| } |
| |
| message VNameMask { |
| bool signature = 1; |
| bool corpus = 2; |
| bool root = 3; |
| bool path = 4; |
| bool language = 5; |
| } |
| |
| // An Entry associates a fact with a graph object (node or edge). This is the |
| // the primary unit of storage. |
| message Entry { |
| VName source = 1; |
| |
| // The following two fields must either be both empty, or both nonempty. |
| string edge_kind = 2; |
| VName target = 3; |
| |
| // The grammar for fact_name: |
| // name = "/" | 1*path |
| // path = "/" word |
| // word = 1*{LETTER|DIGIT|PUNCT} |
| // LETTER = [A-Za-z] |
| // DIGIT = [0-9] |
| // PUNCT = [-.@#$%&_+:()] |
| string fact_name = 4; |
| bytes fact_value = 5; |
| } |
| |
| // A collection of Entry instances. |
| message Entries { |
| repeated Entry entries = 1; |
| } |
| |
| // Request for a stream of Entry objects from a GraphStore. Read operations |
| // should be implemented with time complexity proportional to the size of the |
| // return set. |
| message ReadRequest { |
| // Return entries having this source VName, which may not be empty. |
| VName source = 1; |
| |
| // Return entries having this edge kind; if empty, only entries with an empty |
| // edge kind are returned; if "*", entries of any edge kind are returned. |
| string edge_kind = 2; |
| } |
| |
| // Request to write Entry objects to a GraphStore |
| message WriteRequest { |
| message Update { |
| string edge_kind = 1; |
| VName target = 2; |
| string fact_name = 3; |
| bytes fact_value = 4; |
| } |
| |
| VName source = 1; |
| repeated Update update = 2; |
| } |
| |
| // Response to a WriteRequest |
| message WriteReply {} |
| |
| // Request for a stream of Entry objects resulting from a full scan of a |
| // GraphStore. |
| message ScanRequest { |
| // Return entries having this target VName; if empty, any target field is |
| // matched, including empty. |
| VName target = 1; |
| |
| // Return entries having this kind; if empty, any kind is matched, including |
| // empty. |
| string edge_kind = 2; |
| |
| // Return entries having fact labels with this prefix; if empty, any fact |
| // label is matched, |
| string fact_prefix = 3; |
| } |
| |
| // Request for the size of the shard at the given index. |
| message CountRequest { |
| int64 index = 1; |
| int64 shards = 2; |
| } |
| |
| // Response for a CountRequest |
| message CountReply { |
| // Total number of entries in the specified shard. |
| int64 entries = 1; |
| } |
| |
| // Request for a stream of Entry objects in the given shard. |
| message ShardRequest { |
| int64 index = 1; |
| int64 shards = 2; |
| } |
| |
| // A VNameRewriteRule associates a regular expression pattern with a VName |
| // template. A rule can be applied to a string to produce a VName. |
| message VNameRewriteRule { |
| // An RE2 pattern to match against an input string. Patterns are implicitly |
| // anchored at both ends. |
| string pattern = 1; |
| |
| // A template VName to populate with matches from the input. The template |
| // strings may contain markers of the form @n@, that will be replaced by the |
| // n'th regexp group on a successful input match. |
| VName v_name = 2 [json_name = "vname"]; |
| } |
| |
| // VNameRewriteRules is a container for multiple VNameRewriteRules. |
| message VNameRewriteRules { |
| repeated VNameRewriteRule rule = 1; |
| } |