feat: add GetDynamicDashboard to DashboardService

pkg/dashboard/dashboard.go

@@ -0,0 +1,69 @@
+package dashboard
+
+import (
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/resources"
+)
+
+// Dashboard represents the deployment overview returned by the dashboard and
+// dynamic dashboard endpoints: the deployments themselves in Items, plus the
+// reference data needed to resolve the IDs those items carry.
+type Dashboard struct {
+	Items         []*DashboardItem         `json:"Items"`
+	Projects      []*DashboardProject      `json:"Projects"`
+	ProjectGroups []*DashboardProjectGroup `json:"ProjectGroups"`
+	Environments  []*DashboardEnvironment  `json:"Environments"`
+	Tenants       []*DashboardTenant       `json:"Tenants"`
+
+	// ProjectLimit is set when the server caps how many projects the dashboard
+	// reports on, and is nil when no cap applies. Callers showing a full list
+	// should say so rather than presenting capped results as complete.
+	ProjectLimit *int `json:"ProjectLimit"`
+
+	// IsFiltered reports whether the server narrowed the response, either from
+	// the query or from the caller's permissions.
+	IsFiltered bool `json:"IsFiltered"`
+
+	resources.Resource
+}
+
+// DashboardProject is the subset of a project the dashboard returns to
+// accompany its items.
+type DashboardProject struct {
+	Name                           string   `json:"Name,omitempty"`
+	Slug                           string   `json:"Slug,omitempty"`
+	ProjectGroupID                 string   `json:"ProjectGroupId,omitempty"`
+	EnvironmentIDs                 []string `json:"EnvironmentIds,omitempty"`
+	TenantedDeploymentMode         string   `json:"TenantedDeploymentMode,omitempty"`
+	CanPerformUntenantedDeployment bool     `json:"CanPerformUntenantedDeployment"`
+	IsDisabled                     bool     `json:"IsDisabled"`
+
+	resources.Resource
+}
+
+// DashboardEnvironment is the subset of an environment the dashboard returns to
+// accompany its items.
+type DashboardEnvironment struct {
+	Name string `json:"Name,omitempty"`
+
+	resources.Resource
+}
+
+// DashboardProjectGroup is the subset of a project group the dashboard returns
+// to accompany its items.
+type DashboardProjectGroup struct {
+	Name           string   `json:"Name,omitempty"`
+	EnvironmentIDs []string `json:"EnvironmentIds,omitempty"`
+
+	resources.Resource
+}
+
+// DashboardTenant is the subset of a tenant the dashboard returns to accompany
+// its items.
+type DashboardTenant struct {
+	Name                string              `json:"Name,omitempty"`
+	TenantTags          []string            `json:"TenantTags,omitempty"`
+	ProjectEnvironments map[string][]string `json:"ProjectEnvironments,omitempty"`
+	IsDisabled          bool                `json:"IsDisabled"`
+
+	resources.Resource
+}

pkg/dashboard/dashboard_dynamic_query.go

@@ -1,7 +1,12 @@
 package dashboard
 
 type DashboardDynamicQuery struct {
+	// Environments narrows the dashboard to these environments. The server
+	// matches on ID only: an environment name matches nothing and yields an
+	// empty dashboard rather than an error.
 	Environments    []string `uri:"environments,omitempty" url:"environments,omitempty"`
 	IncludePrevious bool     `uri:"includePrevious,omitempty" url:"includePrevious,omitempty"`
-	Projects        []string `uri:"projects,omitempty" url:"projects,omitempty"`
+	// Projects narrows the dashboard to these projects. As with Environments,
+	// the server matches on ID only.
+	Projects []string `uri:"projects,omitempty" url:"projects,omitempty"`
 }

pkg/dashboard/dashboard_item.go

@@ -1,28 +1,43 @@
 package dashboard
 
-import "time"
+import (
+	"time"
+
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/interruptions"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/resources"
+)
 
 type DashboardItem struct {
-	ChannelID               string     `json:"ChannelId,omitempty"`
-	CompletedTime           *time.Time `json:"CompletedTime,omitempty"`
-	Created                 *time.Time `json:"Created,omitempty"`
-	DeploymentID            string     `json:"DeploymentId,omitempty"`
-	Duration                string     `json:"Duration,omitempty"`
-	EnvironmentID           string     `json:"EnvironmentId,omitempty"`
-	ErrorMessage            string     `json:"ErrorMessage,omitempty"`
-	HasPendingInterruptions bool       `json:"HasPendingInterruptions"`
-	HasWarningsOrErrors     bool       `json:"HasWarningsOrErrors"`
-	IsCompleted             bool       `json:"IsCompleted"`
-	IsCurrent               bool       `json:"IsCurrent"`
-	IsPrevious              bool       `json:"IsPrevious"`
-	ProjectID               string     `json:"ProjectId,omitempty"`
-	QueueTime               *time.Time `json:"QueueTime,omitempty"`
-	ReleaseID               string     `json:"ReleaseId,omitempty"`
-	ReleaseVersion          string     `json:"ReleaseVersion,omitempty"`
-	StartTime               *time.Time `json:"StartTime,omitempty"`
+	ChannelID                string                           `json:"ChannelId,omitempty"`
+	CompletedTime            *time.Time                       `json:"CompletedTime,omitempty"`
+	Created                  *time.Time                       `json:"Created,omitempty"`
+	DeploymentID             string                           `json:"DeploymentId,omitempty"`
+	Duration                 string                           `json:"Duration,omitempty"`
+	EnvironmentID            string                           `json:"EnvironmentId,omitempty"`
+	ErrorMessage             string                           `json:"ErrorMessage,omitempty"`
+	HasPendingInterruptions  bool                             `json:"HasPendingInterruptions"`
+	HasPendingPreconditions  bool                             `json:"HasPendingPreconditions"`
+	HasWarningsOrErrors      bool                             `json:"HasWarningsOrErrors"`
+	IsCompleted              bool                             `json:"IsCompleted"`
+	IsCurrent                bool                             `json:"IsCurrent"`
+	IsPrevious               bool                             `json:"IsPrevious"`
+	PendingInterruptionTypes []interruptions.InterruptionType `json:"PendingInterruptionTypes,omitempty"`
+	// PendingPreconditionTypes is an open set of strings server side rather than
+	// a fixed enum, so it is not typed.
+	PendingPreconditionTypes []string   `json:"PendingPreconditionTypes,omitempty"`
+	ProjectID                string     `json:"ProjectId,omitempty"`
+	QueueTime                *time.Time `json:"QueueTime,omitempty"`
+	ReleaseID                string     `json:"ReleaseId,omitempty"`
+	ReleaseVersion           string     `json:"ReleaseVersion,omitempty"`
+	StartTime                *time.Time `json:"StartTime,omitempty"`
 
 	// Enum: [Canceled Cancelling Executing Failed Queued Success TimedOut]
 	State    string `json:"State,omitempty"`
 	TaskID   string `json:"TaskId,omitempty"`
 	TenantID string `json:"TenantId,omitempty"`
+
+	// Resource carries the item's own Id and Links, which the dashboard returns
+	// for each item and which callers need to reach the deployment, release and
+	// task without reassembling paths from the IDs above.
+	resources.Resource
 }

pkg/dashboard/dashboard_service.go

@@ -1,8 +1,11 @@
 package dashboard
 
 import (
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/internal"
 	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/constants"
 	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/services"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/services/api"
+	"github.com/OctopusDeploy/go-octopusdeploy/v2/uritemplates"
 	"github.com/dghubble/sling"
 )
 
@@ -18,3 +21,43 @@ func NewDashboardService(sling *sling.Sling, uriTemplate string, dashboardDynami
 		Service:              services.NewService(constants.ServiceDashboardService, sling, uriTemplate),
 	}
 }
+
+// GetDynamicDashboard returns the release currently deployed to each
+// environment, optionally narrowed to the given projects and environments, and
+// optionally including the deployment preceding the current one.
+//
+// Passing a zero-valued query returns every project and environment the caller
+// can see, subject to the server's project limit.
+//
+// The query filters on IDs, not names. The server does not reject a name, it
+// simply matches nothing, so a name-filtered call returns an empty dashboard
+// that is indistinguishable from nothing being deployed.
+func (s *DashboardService) GetDynamicDashboard(query DashboardDynamicQuery) (*Dashboard, error) {
+	path, err := s.getDynamicDashboardPath(query)
+	if err != nil {
+		return nil, err
+	}
+
+	response, err := api.ApiGet(s.GetClient(), new(Dashboard), path)
+	if err != nil {
+		return nil, err
+	}
+
+	return response.(*Dashboard), nil
+}
+
+// getDynamicDashboardPath expands the dynamic dashboard link template with the
+// query. The dynamic dashboard has its own link rather than living under the
+// service's URI template, so it is parsed here instead of via GetURITemplate.
+func (s *DashboardService) getDynamicDashboardPath(query DashboardDynamicQuery) (string, error) {
+	if internal.IsEmpty(s.dashboardDynamicPath) {
+		return "", internal.CreateInvalidParameterError(constants.OperationGet, "dashboardDynamicPath")
+	}
+
+	template, err := uritemplates.Parse(s.dashboardDynamicPath)
+	if err != nil {
+		return "", err
+	}
+
+	return template.Expand(query)
+}