feat: beginning of support for multiple pipelines/freight per stage

api/service/v1alpha1/service.proto

@@ -58,7 +58,7 @@ service KargoService {
   rpc DeleteFreight(DeleteFreightRequest) returns (DeleteFreightResponse);
   rpc GetFreight(GetFreightRequest) returns (GetFreightResponse);
   rpc PromoteToStage(PromoteToStageRequest) returns (PromoteToStageResponse);
-  rpc PromoteToStageSubscribers(PromoteToStageSubscribersRequest) returns (PromoteToStageSubscribersResponse);
+  rpc PromoteDownstream(PromoteDownstreamRequest) returns (PromoteDownstreamResponse);
   rpc QueryFreight(QueryFreightRequest) returns (QueryFreightResponse);
   rpc UpdateFreightAlias(UpdateFreightAliasRequest) returns (UpdateFreightAliasResponse);
 
@@ -385,14 +385,14 @@ message PromoteToStageResponse {
   git.luolix.top.akuity.kargo.api.v1alpha1.Promotion promotion = 1;
 }
 
-message PromoteToStageSubscribersRequest {
+message PromoteDownstreamRequest {
   string project = 1;
   string stage = 2;
   string freight = 3;
   string freight_alias = 4 [json_name = "freightAlias"];
 }
 
-message PromoteToStageSubscribersResponse {
+message PromoteDownstreamResponse {
   repeated git.luolix.top.akuity.kargo.api.v1alpha1.Promotion promotions = 1;
 }
 

api/v1alpha1/stage_types.go

@@ -146,11 +146,17 @@ type StageSpec struct {
 	// kargo.akuity.io/shard label with the value of this field. When this field
 	// is empty, the webhook will ensure that label is absent.
 	Shard string `json:"shard,omitempty" protobuf:"bytes,4,opt,name=shard"`
-	// Subscriptions describes the Stage's sources of Freight. This is a required
-	// field.
+	// RequestedFreight expresses the Stage's need for certain pieces of Freight,
+	// each having originated from a particular Warehouse. This list must be
+	// non-empty. In the common case, a Stage will request Freight having
+	// originated from just one specific Warehouse. In advanced cases, requesting
+	// Freight from multiple Warehouses provides a method of advancing new
+	// artifacts of different types through parallel pipelines at different
+	// speeds. This can be useful, for instance, if a Stage is home to multiple
+	// microservices that are independently versioned.
 	//
-	// +kubebuilder:validation:Required
-	Subscriptions Subscriptions `json:"subscriptions" protobuf:"bytes,1,opt,name=subscriptions"`
+	// +kubebuilder:validation:MinItems=1
+	RequestedFreight []FreightRequest `json:"requestedFreight" protobuf:"bytes,1,rep,name=requestedFreight"`
 	// PromotionMechanisms describes how to incorporate Freight into the Stage.
 	// This is an optional field as it is sometimes useful to aggregates available
 	// Freight from multiple upstream Stages without performing any actions. The
@@ -163,23 +169,30 @@ type StageSpec struct {
 	Verification *Verification `json:"verification,omitempty" protobuf:"bytes,3,opt,name=verification"`
 }
 
-// Subscriptions describes a Stage's sources of Freight.
-type Subscriptions struct {
-	// Warehouse is a subscription to a Warehouse. This field is mutually
-	// exclusive with the UpstreamStages field.
-	Warehouse string `json:"warehouse,omitempty" protobuf:"bytes,1,opt,name=warehouse"`
-	// UpstreamStages identifies other Stages as potential sources of Freight
-	// for this Stage. This field is mutually exclusive with the Repos field.
-	UpstreamStages []StageSubscription `json:"upstreamStages,omitempty" protobuf:"bytes,2,rep,name=upstreamStages"`
-}
-
-// StageSubscription defines a subscription to Freight from another Stage.
-type StageSubscription struct {
-	// Name specifies the name of a Stage.
+// FreightRequest expresses a Stage's need for Freight having originated from a
+// particular Warehouse.
+type FreightRequest struct {
+	// Origin specifies what Warehouse the requested Freight must have originated
+	// from. This is a required field.
 	//
-	// +kubebuilder:validation:MinLength=1
-	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
-	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
+	// +kubebuilder:validation:Required
+	Origin string `json:"origin" protobuf:"bytes,1,opt,name=origin"`
+	// Sources describes where the requested Freight may be obtained from. This is
+	// a required field.
+	Sources FreightSources `json:"sources" protobuf:"bytes,2,opt,name=sources"`
+}
+
+type FreightSources struct {
+	// Direct indicates the requested Freight may be obtained directly from the
+	// Warehouse from which it originated. If this field's value is false, then
+	// the value of the Stages field must be non-empty. i.e. Between the two
+	// fields, at least one source must be specified.
+	Direct bool `json:"direct,omitempty" protobuf:"varint,1,opt,name=direct"`
+	// Stages identifies other "upstream" Stages as potential sources of the
+	// requested Freight. If this field's value is empty, then the value of the
+	// Direct field must be true. i.e. Between the two fields, at least on source
+	// must be specified.
+	Stages []string `json:"stages,omitempty" protobuf:"bytes,2,rep,name=stages"`
 }
 
 // PromotionMechanisms describes how to incorporate Freight into a Stage.

charts/kargo/resources/crds/kargo.akuity.io_stages.yaml

@@ -460,6 +460,54 @@ spec:
                       type: object
                     type: array
                 type: object
+              requestedFreight:
+                description: |-
+                  RequestedFreight expresses the Stage's need for certain pieces of Freight,
+                  each having originated from a particular Warehouse. This list must be
+                  non-empty. In the common case, a Stage will request Freight having
+                  originated from just one specific Warehouse. In advanced cases, requesting
+                  Freight from multiple Warehouses provides a method of advancing new
+                  artifacts of different types through parallel pipelines at different
+                  speeds. This can be useful, for instance, if a Stage is home to multiple
+                  microservices that are independently versioned.
+                items:
+                  description: |-
+                    FreightRequest expresses a Stage's need for Freight having originated from a
+                    particular Warehouse.
+                  properties:
+                    origin:
+                      description: |-
+                        Origin specifies what Warehouse the requested Freight must have originated
+                        from. This is a required field.
+                      type: string
+                    sources:
+                      description: |-
+                        Sources describes where the requested Freight may be obtained from. This is
+                        a required field.
+                      properties:
+                        direct:
+                          description: |-
+                            Direct indicates the requested Freight may be obtained directly from the
+                            Warehouse from which it originated. If this field's value is false, then
+                            the value of the Stages field must be non-empty. i.e. Between the two
+                            fields, at least one source must be specified.
+                          type: boolean
+                        stages:
+                          description: |-
+                            Stages identifies other "upstream" Stages as potential sources of the
+                            requested Freight. If this field's value is empty, then the value of the
+                            Direct field must be true. i.e. Between the two fields, at least on source
+                            must be specified.
+                          items:
+                            type: string
+                          type: array
+                      type: object
+                  required:
+                  - origin
+                  - sources
+                  type: object
+                minItems: 1
+                type: array
               shard:
                 description: |-
                   Shard is the name of the shard that this Stage belongs to. This is an
@@ -468,34 +516,6 @@ spec:
                   kargo.akuity.io/shard label with the value of this field. When this field
                   is empty, the webhook will ensure that label is absent.
                 type: string
-              subscriptions:
-                description: |-
-                  Subscriptions describes the Stage's sources of Freight. This is a required
-                  field.
-                properties:
-                  upstreamStages:
-                    description: |-
-                      UpstreamStages identifies other Stages as potential sources of Freight
-                      for this Stage. This field is mutually exclusive with the Repos field.
-                    items:
-                      description: StageSubscription defines a subscription to Freight
-                        from another Stage.
-                      properties:
-                        name:
-                          description: Name specifies the name of a Stage.
-                          minLength: 1
-                          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
-                          type: string
-                      required:
-                      - name
-                      type: object
-                    type: array
-                  warehouse:
-                    description: |-
-                      Warehouse is a subscription to a Warehouse. This field is mutually
-                      exclusive with the UpstreamStages field.
-                    type: string
-                type: object
               verification:
                 description: |-
                   Verification describes how to verify a Stage's current Freight is fit for
@@ -554,7 +574,7 @@ spec:
                     type: array
                 type: object
             required:
-            - subscriptions
+            - requestedFreight
             type: object
           status:
             description: Status describes the Stage's current and recent Freight,