dm/api/service/v1/walk_graph.proto

// Copyright 2016 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

syntax = "proto3";

option go_package = "go.chromium.org/luci/dm/api/service/v1;dm";

import "google/protobuf/duration.proto";

import "go.chromium.org/luci/dm/api/service/v1/graph_data.proto";
import "go.chromium.org/luci/dm/api/service/v1/graph_query.proto";
import "go.chromium.org/luci/dm/api/service/v1/types.proto";

package dm;

// WalkGraphReq allows you to walk from one or more Quests through their
// Attempt's forward dependencies.
//
//
// The handler will evaluate all of the queries, executing them in parallel.
// For each attempt or quest produced by the query, it will queue a walk
// operation for that node, respecting the options set (max_depth, etc.).
message WalkGraphReq {
  // Optional. See Include.AttemptResult for restrictions.
  dm.Execution.Auth auth = 1;

  // Query specifies a list of queries to start the graph traversal on. The
  // traversal will occur as a union of the query results. Redundant
  // specification will not cause additional heavy work; every graph node will
  // be processed exactly once, regardless of how many times it appears in the
  // query results. However, redundancy in the queries will cause the server to
  // retrieve and discard more information.
  GraphQuery query = 2;

  message Mode {
    // DFS sets whether this is a Depth-first (ish) or a Breadth-first (ish) load.
    // Since the load operation is multi-threaded, the search order is best
    // effort, but will actually be some hybrid between DFS and BFS. This setting
    // controls the bias direction of the hybrid loading algorithm.
    bool dfs = 1;

    // Direction indicates that direction of dependencies that the request should
    // walk.
    enum Direction {
      FORWARDS = 0;
      BACKWARDS = 1;
      BOTH = 2;
    }
    Direction direction = 2;
  }
  Mode mode = 3;

  message Limit {
    // MaxDepth sets the number of attempts to traverse; 0 means 'immediate'
    // (no dependencies), -1 means 'no limit', and >0 is a limit.
    //
    // Any negative value besides -1 is an error.
    int64 max_depth = 1;

    // MaxTime sets the maximum amount of time that the query processor should
    // take. Application of this deadline is 'best effort', which means the query
    // may take a bit longer than this timeout and still attempt to return data.
    //
    // This is different than the grpc timeout header, which will set a hard
    // deadline for the request.
    google.protobuf.Duration max_time = 2;

    // MaxDataSize sets the maximum amount of 'Data' (in bytes) that can be
    // returned, if include.quest_data, include.attempt_data, and/or
    // include.attempt_result are set. If this limit is hit, then the
    // appropriate 'partial' value will be set for that object, but the base
    // object would still be included in the result.
    //
    // If this limit is 0, a default limit of 16MB will be used. If this limit
    // exceeds 30MB, it will be reduced to 30MB.
    uint32 max_data_size = 3;
  }
  Limit limit = 4;

  message Include {
    message Options {
      // Fills the 'id' field.
      //
      // If this is false, it will be omitted.
      //
      // Note that there's enough information contextually to derive these ids
      // on the client side, though it can be handy to have the server produce
      // them for you.
      bool ids = 1;

      // Instructs the request to include the Data field
      bool data = 2;

      // Instructs finished objects to include the Result field.
      //
      // If the requestor is an execution, the query logic will only include the
      // result if the execution's Attempt depends on it, otherwise it will be
      // blank.
      //
      // If the request's cumulative result data would be more than
      // limit.max_data_size of data, the remaining results will have their
      // Partial.Result set to DATA_SIZE_LIMIT.
      //
      // Has no effect for Quests.
      bool result = 3;

      // If set to true, objects with an abnormal termination will be included.
      bool abnormal = 4;

      // If set to true, expired objects will be included.
      bool expired = 5;
    }
    Options quest = 1;
    Options attempt = 2;
    Options execution = 3;

    // Executions is the number of Executions to include per Attempt. If this
    // is 0, then the execution data will be omitted completely.
    //
    // Executions included are from high ids to low ids. So setting this to `1`
    // would return the LAST execution made for this Attempt.
    uint32 num_executions = 4;

    // FwdDeps instructs WalkGraph to include forward dependency information
    // from the result. This only changes the presence of information in the
    // result; if the query is walking forward attempt dependencies, that will
    // still occur even if this is false.
    bool fwd_deps = 5;

    // BackDeps instructs WalkGraph to include the backwards dependency
    // information. This only changes the presence of information in the result;
    // if the query is walking backward attempt dependencies, that will still
    // occur even if this is false.
    bool back_deps = 6;
  }
  // Include allows you to add additional information to the returned
  // GraphData which is typically medium-to-large sized.
  Include include = 5;

  message Exclude {
    // Do not include data from the following quests in the response.
    repeated string quests = 1;

    // Do not include data from the following attempts in the response.
    dm.AttemptList attempts = 2;
  }
  Exclude exclude = 6;
}