Skip to content

docs: API workspace agents and builds - #5538

Merged
mtojek merged 20 commits into
coder:mainfrom
mtojek:3522-workspacebuilds-1
Jan 5, 2023
Merged

mtojek merged 20 commits into
coder:mainfrom
mtojek:3522-workspacebuilds-1

Conversation

@mtojek

@mtojek mtojek commented Jan 2, 2023 •

Copy link
Copy Markdown
Member

Related: #3522

Blocker: #5506 (this PR is built on top of that branch)

Changes:

  • workspaceagents.go
  • workspacebuilds.go (also affects /workspaces)

@mtojek mtojek self-assigned this Jan 2, 2023
@mtojek mtojek mentioned this pull request Jan 2, 2023
28 of 29 tasks
@mtojek
mtojek requested review from bpmct and mafredri January 3, 2023 18:47
@mtojek
mtojek marked this pull request as ready for review January 3, 2023 18:48
Comment thread coderd/workspaceagents.go Resolved
@mtojek mtojek changed the title docs: workspace agents and builds docs: API workspace agents and builds Jan 4, 2023

@mafredri mafredri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some minor questions and suggestions but looks good in all! 👍🏻

Comment thread coderd/workspacebuilds.go Resolved
Comment thread coderd/workspaceagents.go Resolved
DisconnectedAt *time.Time `json:"disconnected_at,omitempty"`
Status WorkspaceAgentStatus `json:"status"`
ID uuid.UUID `json:"id" format:"uuid"`
CreatedAt time.Time `json:"created_at" format:"date-time"`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps I've asked before, but is there a way to automatically transform these based on the Go type? It seems unfortunate we'd have to tag every new struct, and we will almost certainly miss to add the tag to fields in the future.

It'd be nice if format was reserved as an override since uuid and time.Time are essentially never a different format (would take a custom json Marshaller at which point using format would be appropriate).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm afraid that we would need a fork to apply this feature, let's say, auto-format. It doesn't look like something we can truly solve just with validation.

I'm not sure why it hasn't been implemented this way. Even official examples suggest using format tags.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can certainly understand why it's not the default (due to middlewares and handlers that can do whatever). But it'd be nice to enable such a feature.

Do you think they'd be open to it if we made a PR? Seems like many people could benefit.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the moment, we're using version swaggo v1.8.6, but I can try to bump it to v1.8.9 so that we will also benefit from future PRs. AFAIR v1.8.9 added a lot of noise around all possible values of time.Duration or strange value examples:

-    "value": 0
+    "value": -9223372036854776000

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, if v1.8.9 is problematic we can punt it for now unless you think there's a benefit to upgrading?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me prepare a draft PR and we can discuss the upgrade there.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

InitiatorUsername string `json:"initiator_name"`
Job ProvisionerJob `json:"job"`
Reason BuildReason `db:"reason" json:"reason"`
Reason BuildReason `db:"reason" json:"reason" enums:"initiator,autostart,autostop"`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work! Once we get the docs in shape, it'd be nice to try to process the Go code to find these enums automatically.

Btw, would it be possible to move this enum description to the type? Like:

// BuildReason ...
// @enum initiator,autostart,autostop
type BuildReason string

Perhaps not supported by swaggo.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some magic undocumented extensions like x-enum-varnames or x-enum-descriptions, but I don't think that this is what we're looking for.

See swaggo/swag#984

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, that seems useful with enums that are number based and have string representations in (de-)serialization.

Comment thread docs/api/agents.md Resolved
DisconnectedAt *time.Time `json:"disconnected_at,omitempty"`
Status WorkspaceAgentStatus `json:"status"`
ID uuid.UUID `json:"id" format:"uuid"`
CreatedAt time.Time `json:"created_at" format:"date-time"`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, if v1.8.9 is problematic we can punt it for now unless you think there's a benefit to upgrading?

@mtojek
mtojek merged commit 66fa2a1 into coder:main Jan 5, 2023
@github-actions github-actions Bot locked and limited conversation to collaborators Jan 5, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants