@flyteorg/flyteidl 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flyteorg/flyteidl",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Compiled protocol buffers and gRPC service clients/servers for Flyte IDLs",
   "repository": {
     "type": "git",

package/protos/docs/admin/admin.rst

@@ -3114,6 +3114,169 @@ Represents a frequency at which to run a schedule.
 
 
 
+.. _ref_flyteidl/admin/signal.proto:
+
+flyteidl/admin/signal.proto
+==================================================================
+
+
+
+
+
+.. _ref_flyteidl.admin.Signal:
+
+Signal
+------------------------------------------------------------------
+
+Signal encapsulates a unique identifier, associated metadata, and a value for a single Flyte
+signal. Signals may exist either without a set value (representing a signal request) or with a
+populated value (indicating the signal has been given).
+
+
+
+.. csv-table:: Signal type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "id", ":ref:`ref_flyteidl.core.SignalIdentifier`", "", "A unique identifier for the requested signal."
+   "type", ":ref:`ref_flyteidl.core.LiteralType`", "", "A type denoting the required value type for this signal."
+   "value", ":ref:`ref_flyteidl.core.Literal`", "", "The value of the signal. This is only available if the signal has been "set" and must match the defined the type."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SignalGetOrCreateRequest:
+
+SignalGetOrCreateRequest
+------------------------------------------------------------------
+
+SignalGetOrCreateRequest represents a request structure to retrive or create a signal.
+See :ref:`ref_flyteidl.admin.Signal` for more details
+
+
+
+.. csv-table:: SignalGetOrCreateRequest type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "id", ":ref:`ref_flyteidl.core.SignalIdentifier`", "", "A unique identifier for the requested signal."
+   "type", ":ref:`ref_flyteidl.core.LiteralType`", "", "A type denoting the required value type for this signal."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SignalList:
+
+SignalList
+------------------------------------------------------------------
+
+SignalList represents collection of signals along with the token of the last result.
+See :ref:`ref_flyteidl.admin.Signal` for more details
+
+
+
+.. csv-table:: SignalList type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "signals", ":ref:`ref_flyteidl.admin.Signal`", "repeated", "A list of signals matching the input filters."
+   "token", ":ref:`ref_string`", "", "In the case of multiple pages of results, the server-provided token can be used to fetch the next page in a query. If there are no more results, this value will be empty."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SignalListRequest:
+
+SignalListRequest
+------------------------------------------------------------------
+
+SignalListRequest represents a request structure to retrieve a collection of signals.
+See :ref:`ref_flyteidl.admin.Signal` for more details
+
+
+
+.. csv-table:: SignalListRequest type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "workflow_execution_id", ":ref:`ref_flyteidl.core.WorkflowExecutionIdentifier`", "", "Indicates the workflow execution to filter by. +required"
+   "limit", ":ref:`ref_uint32`", "", "Indicates the number of resources to be returned. +required"
+   "token", ":ref:`ref_string`", "", "In the case of multiple pages of results, the, server-provided token can be used to fetch the next page in a query. +optional"
+   "filters", ":ref:`ref_string`", "", "Indicates a list of filters passed as string. +optional"
+   "sort_by", ":ref:`ref_flyteidl.admin.Sort`", "", "Sort ordering. +optional"
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SignalSetRequest:
+
+SignalSetRequest
+------------------------------------------------------------------
+
+SignalSetRequest represents a request structure to set the value on a signal. Setting a signal
+effetively satisfies the signal condition within a Flyte workflow.
+See :ref:`ref_flyteidl.admin.Signal` for more details
+
+
+
+.. csv-table:: SignalSetRequest type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "id", ":ref:`ref_flyteidl.core.SignalIdentifier`", "", "A unique identifier for the requested signal."
+   "value", ":ref:`ref_flyteidl.core.Literal`", "", "The value of this signal, must match the defining signal type."
+
+
+
+
+
+
+
+.. _ref_flyteidl.admin.SignalSetResponse:
+
+SignalSetResponse
+------------------------------------------------------------------
+
+SignalSetResponse represents a response structure if signal setting succeeds.
+
+Purposefully empty, may be populated in the future.
+
+
+
+
+
+
+
+..
+   end messages
+
+
+..
+   end enums
+
+
+..
+   end HasExtensions
+
+
+..
+   end services
+
+
+
+
 .. _ref_flyteidl/admin/task.proto:
 
 flyteidl/admin/task.proto

package/protos/docs/core/core.rst

@@ -947,6 +947,28 @@ Encapsulation of fields that identify a Flyte node execution entity.
 
 
 
+.. _ref_flyteidl.core.SignalIdentifier:
+
+SignalIdentifier
+------------------------------------------------------------------
+
+Encapsulation of fields the uniquely identify a signal.
+
+
+
+.. csv-table:: SignalIdentifier type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "signal_id", ":ref:`ref_string`", "", "Unique identifier for a signal."
+   "execution_id", ":ref:`ref_flyteidl.core.WorkflowExecutionIdentifier`", "", "Identifies the Flyte workflow execution this signal belongs to."
+
+
+
+
+
+
+
 .. _ref_flyteidl.core.TaskExecutionIdentifier:
 
 TaskExecutionIdentifier
@@ -2824,6 +2846,28 @@ Links a variable to an alias.
 
 
 
+.. _ref_flyteidl.core.ApproveCondition:
+
+ApproveCondition
+------------------------------------------------------------------
+
+ApproveCondition represents a dependency on an external approval. During execution, this will manifest as a boolean
+signal with the provided signal_id.
+
+
+
+.. csv-table:: ApproveCondition type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "signal_id", ":ref:`ref_string`", "", "A unique identifier for the requested boolean signal."
+
+
+
+
+
+
+
 .. _ref_flyteidl.core.BranchNode:
 
 BranchNode
@@ -2846,6 +2890,29 @@ runtime based on a series of conditions that get evaluated on various parameters
 
 
 
+.. _ref_flyteidl.core.GateNode:
+
+GateNode
+------------------------------------------------------------------
+
+GateNode refers to the condition that is required for the gate to successfully complete.
+
+
+
+.. csv-table:: GateNode type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "approve", ":ref:`ref_flyteidl.core.ApproveCondition`", "", "ApproveCondition represents a dependency on an external approval provided by a boolean signal."
+   "signal", ":ref:`ref_flyteidl.core.SignalCondition`", "", "SignalCondition represents a dependency on an signal."
+   "sleep", ":ref:`ref_flyteidl.core.SleepCondition`", "", "SleepCondition represents a dependency on waiting for the specified duration."
+
+
+
+
+
+
+
 .. _ref_flyteidl.core.IfBlock:
 
 IfBlock
@@ -2915,6 +2982,7 @@ node.
    "task_node", ":ref:`ref_flyteidl.core.TaskNode`", "", "Information about the Task to execute in this node."
    "workflow_node", ":ref:`ref_flyteidl.core.WorkflowNode`", "", "Information about the Workflow to execute in this mode."
    "branch_node", ":ref:`ref_flyteidl.core.BranchNode`", "", "Information about the branch node to evaluate in this node."
+   "gate_node", ":ref:`ref_flyteidl.core.GateNode`", "", "Information about the condition to evaluate in this node."
 
 
 
@@ -2946,6 +3014,50 @@ Defines extra information about the Node.
 
 
 
+.. _ref_flyteidl.core.SignalCondition:
+
+SignalCondition
+------------------------------------------------------------------
+
+SignalCondition represents a dependency on an signal.
+
+
+
+.. csv-table:: SignalCondition type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "signal_id", ":ref:`ref_string`", "", "A unique identifier for the requested signal."
+   "type", ":ref:`ref_flyteidl.core.LiteralType`", "", "A type denoting the required value type for this signal."
+   "output_variable_name", ":ref:`ref_string`", "", "The variable name for the signal value in this nodes outputs."
+
+
+
+
+
+
+
+.. _ref_flyteidl.core.SleepCondition:
+
+SleepCondition
+------------------------------------------------------------------
+
+SleepCondition represents a dependency on waiting for the specified duration.
+
+
+
+.. csv-table:: SleepCondition type fields
+   :header: "Field", "Type", "Label", "Description"
+   :widths: auto
+
+   "duration", ":ref:`ref_google.protobuf.Duration`", "", "The overall duration for this sleep."
+
+
+
+
+
+
+
 .. _ref_flyteidl.core.TaskNode:
 
 TaskNode

package/protos/docs/service/service.rst

@@ -435,3 +435,45 @@ IdentityService defines an RPC Service that interacts with user/app identities.
    end services
 
 
+
+
+.. _ref_flyteidl/service/signal.proto:
+
+flyteidl/service/signal.proto
+==================================================================
+
+
+
+
+..
+   end messages
+
+
+..
+   end enums
+
+
+..
+   end HasExtensions
+
+
+
+.. _ref_flyteidl.service.SignalService:
+
+SignalService
+------------------------------------------------------------------
+
+SignalService defines an RPC Service that may create, update, and retrieve signal(s).
+
+.. csv-table:: SignalService service methods
+   :header: "Method Name", "Request Type", "Response Type", "Description"
+   :widths: auto
+
+   "GetOrCreateSignal", ":ref:`ref_flyteidl.admin.SignalGetOrCreateRequest`", ":ref:`ref_flyteidl.admin.Signal`", "Fetches or creates a :ref:`ref_flyteidl.admin.Signal`."
+   "ListSignals", ":ref:`ref_flyteidl.admin.SignalListRequest`", ":ref:`ref_flyteidl.admin.SignalList`", "Fetch a list of :ref:`ref_flyteidl.admin.Signal` definitions."
+   "SetSignal", ":ref:`ref_flyteidl.admin.SignalSetRequest`", ":ref:`ref_flyteidl.admin.SignalSetResponse`", "Sets the value on a :ref:`ref_flyteidl.admin.Signal` definition"
+
+..
+   end services
+
+

package/protos/flyteidl/admin/signal.proto

@@ -0,0 +1,86 @@
+syntax = "proto3";
+
+package flyteidl.admin;
+option go_package = "github.com/flyteorg/flyteidl/gen/pb-go/flyteidl/admin";
+
+import "flyteidl/admin/common.proto";
+import "flyteidl/core/identifier.proto";
+import "flyteidl/core/literals.proto";
+import "flyteidl/core/types.proto";
+
+// SignalGetOrCreateRequest represents a request structure to retrive or create a signal.
+// See :ref:`ref_flyteidl.admin.Signal` for more details
+message SignalGetOrCreateRequest {
+    // A unique identifier for the requested signal.
+    core.SignalIdentifier id = 1;
+
+    // A type denoting the required value type for this signal.
+    core.LiteralType type = 2;
+}
+
+// SignalListRequest represents a request structure to retrieve a collection of signals.
+// See :ref:`ref_flyteidl.admin.Signal` for more details
+message SignalListRequest {
+    // Indicates the workflow execution to filter by.
+    // +required
+    core.WorkflowExecutionIdentifier workflow_execution_id = 1;
+
+    // Indicates the number of resources to be returned.
+    // +required
+    uint32 limit = 2;
+
+    // In the case of multiple pages of results, the, server-provided token can be used to fetch the next page
+    // in a query.
+    // +optional
+    string token = 3;
+
+    // Indicates a list of filters passed as string.
+    // +optional
+    string filters = 4;
+
+    // Sort ordering.
+    // +optional
+    Sort sort_by = 5;
+}
+
+// SignalList represents collection of signals along with the token of the last result.
+// See :ref:`ref_flyteidl.admin.Signal` for more details
+message SignalList {
+    // A list of signals matching the input filters.
+    repeated Signal signals = 1;    
+
+    // In the case of multiple pages of results, the server-provided token can be used to fetch the next page
+    // in a query. If there are no more results, this value will be empty.
+    string token = 2;
+}
+
+// SignalSetRequest represents a request structure to set the value on a signal. Setting a signal
+// effetively satisfies the signal condition within a Flyte workflow.
+// See :ref:`ref_flyteidl.admin.Signal` for more details
+message SignalSetRequest {
+    // A unique identifier for the requested signal.
+    core.SignalIdentifier id = 1;    
+
+    // The value of this signal, must match the defining signal type.
+    core.Literal value = 2;
+}
+
+// SignalSetResponse represents a response structure if signal setting succeeds.
+message SignalSetResponse {
+    // Purposefully empty, may be populated in the future.
+}
+
+// Signal encapsulates a unique identifier, associated metadata, and a value for a single Flyte
+// signal. Signals may exist either without a set value (representing a signal request) or with a
+// populated value (indicating the signal has been given).
+message Signal {
+    // A unique identifier for the requested signal.
+    core.SignalIdentifier id = 1;
+
+    // A type denoting the required value type for this signal.
+    core.LiteralType type = 2;
+
+    // The value of the signal. This is only available if the signal has been "set" and must match
+    // the defined the type.
+    core.Literal value = 3;
+}

package/protos/flyteidl/core/identifier.proto

@@ -63,3 +63,12 @@ message TaskExecutionIdentifier {
 
     uint32 retry_attempt     = 3;
 }
+
+// Encapsulation of fields the uniquely identify a signal.
+message SignalIdentifier {
+    // Unique identifier for a signal.
+    string signal_id = 1;
+
+    // Identifies the Flyte workflow execution this signal belongs to.
+    WorkflowExecutionIdentifier execution_id = 2;
+}

package/protos/flyteidl/core/workflow.proto

@@ -68,6 +68,45 @@ message WorkflowNode {
     }
 }
 
+// ApproveCondition represents a dependency on an external approval. During execution, this will manifest as a boolean
+// signal with the provided signal_id.
+message ApproveCondition {
+    // A unique identifier for the requested boolean signal.
+    string signal_id = 1;
+}
+
+// SignalCondition represents a dependency on an signal.
+message SignalCondition {
+    // A unique identifier for the requested signal.
+    string signal_id = 1;
+
+    // A type denoting the required value type for this signal.
+    LiteralType type = 2;
+
+    // The variable name for the signal value in this nodes outputs.
+    string output_variable_name = 3;
+}
+
+// SleepCondition represents a dependency on waiting for the specified duration.
+message SleepCondition {
+    // The overall duration for this sleep.
+    google.protobuf.Duration duration = 1;
+}
+
+// GateNode refers to the condition that is required for the gate to successfully complete.
+message GateNode {
+    oneof condition {
+        // ApproveCondition represents a dependency on an external approval provided by a boolean signal.
+        ApproveCondition approve = 1;
+
+        // SignalCondition represents a dependency on an signal.
+        SignalCondition signal = 2;
+
+        // SleepCondition represents a dependency on waiting for the specified duration.
+        SleepCondition sleep = 3;
+    }
+}
+
 // Defines extra information about the Node.
 message NodeMetadata {
     // A friendly name for the Node
@@ -129,6 +168,9 @@ message Node {
 
         // Information about the branch node to evaluate in this node.
         BranchNode branch_node = 8;
+
+        // Information about the condition to evaluate in this node.
+        GateNode gate_node = 9;
     }
 }
 

package/protos/flyteidl/service/signal.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+package flyteidl.service;
+
+option go_package = "github.com/flyteorg/flyteidl/gen/pb-go/flyteidl/service";
+
+import "google/api/annotations.proto";
+import "flyteidl/admin/signal.proto";
+import "protoc-gen-swagger/options/annotations.proto";
+
+// SignalService defines an RPC Service that may create, update, and retrieve signal(s).
+service SignalService {
+  // Fetches or creates a :ref:`ref_flyteidl.admin.Signal`.
+  rpc GetOrCreateSignal (flyteidl.admin.SignalGetOrCreateRequest) returns (flyteidl.admin.Signal) {
+    // Purposefully left out an HTTP API for this RPC call. This is meant to idempotently retrieve
+    // a signal, meaning the first call will create the signal and all subsequent calls will
+    // fetch the existing signal. This is only useful during Flyte Workflow execution and therefore
+    // is not exposed to mitigate unintended behavior.
+    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+      description: "Retrieve a signal, creating it if it does not exist."
+    };
+  }
+
+  // Fetch a list of :ref:`ref_flyteidl.admin.Signal` definitions.
+  rpc ListSignals (flyteidl.admin.SignalListRequest) returns (flyteidl.admin.SignalList) {
+    option (google.api.http) = {
+      get: "/api/v1/signals/{workflow_execution_id.project}/{workflow_execution_id.domain}/{workflow_execution_id.name}"
+    };
+    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+      description: "Fetch existing signal definitions matching the input signal id filters."
+    };
+  }
+
+  // Sets the value on a :ref:`ref_flyteidl.admin.Signal` definition
+  rpc SetSignal (flyteidl.admin.SignalSetRequest) returns (flyteidl.admin.SignalSetResponse) {
+    option (google.api.http) = {
+      post: "/api/v1/signals"
+      body: "*"
+    };
+    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
+      description: "Set a signal value."
+      responses: {
+        key: "400"
+        value: {
+          description: "Returned for bad request that may have failed validation."
+        }
+      }
+      responses: {
+        key: "409"
+        value: {
+          description: "Returned for a request that references an identical entity that has already been registered."
+        }
+      }
+    };
+  }
+}