From aec3e9e5abf12b8a4c373a7e3e6a6a30232ab030 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Fri, 17 Oct 2025 08:40:56 -0500 Subject: [PATCH] chore: include codersdk comments in typescript output (#20348) Some comments are likely still omitted as guts does not cover all cases right now. And some cases are omitted because the output format is ambiguous on how best to format it. --- go.mod | 2 +- go.sum | 4 +- scripts/apitypings/main.go | 3 + site/src/api/typesGenerated.ts | 1914 +++++++++++++++++++++++++++++++- 4 files changed, 1896 insertions(+), 27 deletions(-) diff --git a/go.mod b/go.mod index 228d3a83ff..7e0338253a 100644 --- a/go.mod +++ b/go.mod @@ -96,7 +96,7 @@ require ( github.com/chromedp/chromedp v0.14.1 github.com/cli/safeexec v1.0.1 github.com/coder/flog v1.1.0 - github.com/coder/guts v1.6.0 + github.com/coder/guts v1.6.1 github.com/coder/pretty v0.0.0-20230908205945-e89ba86370e0 github.com/coder/quartz v0.2.1 github.com/coder/retry v1.5.1 diff --git a/go.sum b/go.sum index 0f97c2e718..2dbaf7d2e0 100644 --- a/go.sum +++ b/go.sum @@ -928,8 +928,8 @@ github.com/coder/go-httpstat v0.0.0-20230801153223-321c88088322 h1:m0lPZjlQ7vdVp github.com/coder/go-httpstat v0.0.0-20230801153223-321c88088322/go.mod h1:rOLFDDVKVFiDqZFXoteXc97YXx7kFi9kYqR+2ETPkLQ= github.com/coder/go-scim/pkg/v2 v2.0.0-20230221055123-1d63c1222136 h1:0RgB61LcNs24WOxc3PBvygSNTQurm0PYPujJjLLOzs0= github.com/coder/go-scim/pkg/v2 v2.0.0-20230221055123-1d63c1222136/go.mod h1:VkD1P761nykiq75dz+4iFqIQIZka189tx1BQLOp0Skc= -github.com/coder/guts v1.6.0 h1:N7zotzWubbT49kiH/RENHNQglW68tyMYymMU452q9yg= -github.com/coder/guts v1.6.0/go.mod h1:FaECwB632JE8nYi7nrKfO0PVjbOl4+hSWupKO2Z99JI= +github.com/coder/guts v1.6.1 h1:bMVBtDNP/1gW58NFRBdzStAQzXlveMrLAnORpwE9tYo= +github.com/coder/guts v1.6.1/go.mod h1:FaECwB632JE8nYi7nrKfO0PVjbOl4+hSWupKO2Z99JI= github.com/coder/pq v1.10.5-0.20250807075151-6ad9b0a25151 h1:YAxwg3lraGNRwoQ18H7R7n+wsCqNve7Brdvj0F1rDnU= github.com/coder/pq v1.10.5-0.20250807075151-6ad9b0a25151/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o= github.com/coder/pretty v0.0.0-20230908205945-e89ba86370e0 h1:3A0ES21Ke+FxEM8CXx9n47SZOKOpgSE1bbJzlE4qPVs= diff --git a/scripts/apitypings/main.go b/scripts/apitypings/main.go index c820bc4e1d..65483a34bc 100644 --- a/scripts/apitypings/main.go +++ b/scripts/apitypings/main.go @@ -17,6 +17,9 @@ func main() { log.Fatalf("new convert: %v", err) } + // Include golang comments to typescript output. + gen.PreserveComments() + generateDirectories := map[string]string{ "github.com/coder/coder/v2/codersdk": "", "github.com/coder/coder/v2/coderd/healthcheck/health": "Health", diff --git a/site/src/api/typesGenerated.ts b/site/src/api/typesGenerated.ts index f6679d3d31..dee5eac22b 100644 --- a/site/src/api/typesGenerated.ts +++ b/site/src/api/typesGenerated.ts @@ -1,6 +1,10 @@ // Code generated by 'guts'. DO NOT EDIT. // From codersdk/templates.go +/** + * ACLAvailable is a list of users and groups that can be added to a template + * ACL. + */ export interface ACLAvailable { readonly users: readonly ReducedUser[]; readonly groups: readonly Group[]; @@ -88,20 +92,42 @@ export interface AIConfig { } // From codersdk/aitasks.go +/** + * AITaskPromptParameterName is the name of the parameter used to pass prompts + * to AI tasks. + * + * Experimental: This value is experimental and may change in the future. + */ export const AITaskPromptParameterName = "AI Prompt"; // From codersdk/aitasks.go +/** + * AITasksPromptsResponse represents the response from the AITaskPrompts method. + * + * Experimental: This method is experimental and may change in the future. + */ export interface AITasksPromptsResponse { + /** + * Prompts is a map of workspace build IDs to prompts. + */ readonly prompts: Record; } // From codersdk/allowlist.go +/** + * APIAllowListTarget represents a single allow-list entry using the canonical + * string form ":". The wildcard symbol "*" is treated as a + * permissive match for either side. + */ export interface APIAllowListTarget { readonly type: RBACResource; readonly id: string; } // From codersdk/apikey.go +/** + * APIKey: do not ever return the HashedSecret + */ export interface APIKey { readonly id: string; readonly user_id: string; @@ -110,7 +136,7 @@ export interface APIKey { readonly created_at: string; readonly updated_at: string; readonly login_type: LoginType; - readonly scope: APIKeyScope; + readonly scope: APIKeyScope; // Deprecated: use Scopes instead. readonly scopes: readonly APIKeyScope[]; readonly token_name: string; readonly lifetime_seconds: number; @@ -516,7 +542,13 @@ export interface APIKeyWithOwner extends APIKey { } // From healthsdk/healthsdk.go +/** + * AccessURLReport shows the results of performing a HTTP_GET to the /healthz endpoint through the configured access URL. + */ export interface AccessURLReport extends BaseReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly access_url: string; readonly reachable: boolean; @@ -551,9 +583,19 @@ export interface AgentScriptTiming { } // From codersdk/templates.go +/** + * AgentStatsReportResponse is returned for each report + * request by the agent. + */ export interface AgentStatsReportResponse { readonly num_comms: number; + /** + * RxBytes is the number of received bytes. + */ readonly rx_bytes: number; + /** + * TxBytes is the number of transmitted bytes. + */ readonly tx_bytes: number; } @@ -568,6 +610,9 @@ export const AgentSubsystems: AgentSubsystem[] = [ // From codersdk/deployment.go export interface AppHostResponse { + /** + * Host is the externally accessible URL for the Coder instance. + */ readonly host: string; } @@ -576,6 +621,9 @@ export interface AppearanceConfig { readonly application_name: string; readonly logo_url: string; readonly docs_url: string; + /** + * Deprecated: ServiceBanner has been replaced by AnnouncementBanners. + */ readonly service_banner: BannerConfig; readonly announcement_banners: readonly BannerConfig[]; readonly support_links?: readonly LinkConfig[]; @@ -583,6 +631,10 @@ export interface AppearanceConfig { // From codersdk/templates.go export interface ArchiveTemplateVersionsRequest { + /** + * By default, only failed versions are archived. Set this to true + * to archive all unused versions regardless of job status. + */ readonly all: boolean; } @@ -595,6 +647,9 @@ export interface ArchiveTemplateVersionsResponse { // From codersdk/roles.go export interface AssignableRoles extends Role { readonly assignable: boolean; + /** + * BuiltIn roles are immutable + */ readonly built_in: boolean; } @@ -651,6 +706,9 @@ export interface AuditLog { readonly user_agent: string; readonly resource_type: ResourceType; readonly resource_id: string; + /** + * ResourceTarget is the name of the resource. + */ readonly resource_target: string; readonly resource_icon: string; readonly action: AuditAction; @@ -660,6 +718,9 @@ export interface AuditLog { readonly description: string; readonly resource_link: string; readonly is_deleted: boolean; + /** + * Deprecated: Use 'organization.id' instead. + */ readonly organization_id: string; readonly organization?: MinimalOrganization; readonly user: User | null; @@ -682,6 +743,9 @@ export interface AuthMethod { } // From codersdk/users.go +/** + * AuthMethods contains authentication method information like whether they are enabled or not or custom text, etc. + */ export interface AuthMethods { readonly terms_of_service_url?: string; readonly password: AuthMethod; @@ -690,22 +754,76 @@ export interface AuthMethods { } // From codersdk/authorization.go +/** + * AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. + * + * @Description AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. + */ export interface AuthorizationCheck { + /** + * Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, and all workspaces across the entire product. + * When defining an object, use the most specific language when possible to + * produce the smallest set. Meaning to set as many fields on 'Object' as + * you can. Example, if you want to check if you can update all workspaces + * owned by 'me', try to also add an 'OrganizationID' to the settings. + * Omitting the 'OrganizationID' could produce the incorrect value, as + * workspaces have both `user` and `organization` owners. + */ readonly object: AuthorizationObject; readonly action: RBACAction; } // From codersdk/authorization.go +/** + * AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, + * all workspaces across the entire product. + * + * @Description AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, + * @Description all workspaces across the entire product. + */ export interface AuthorizationObject { + /** + * ResourceType is the name of the resource. + * `./coderd/rbac/object.go` has the list of valid resource types. + */ readonly resource_type: RBACResource; + /** + * OwnerID (optional) adds the set constraint to all resources owned by a given user. + */ readonly owner_id?: string; + /** + * OrganizationID (optional) adds the set constraint to all resources owned by a given organization. + */ readonly organization_id?: string; + /** + * ResourceID (optional) reduces the set to a singular resource. This assigns + * a resource ID to the resource type, eg: a single workspace. + * The rbac library will not fetch the resource from the database, so if you + * are using this option, you should also set the owner ID and organization ID + * if possible. Be as specific as possible using all the fields relevant. + */ readonly resource_id?: string; + /** + * AnyOrgOwner (optional) will disregard the org_owner when checking for permissions. + * This cannot be set to true if the OrganizationID is set. + */ readonly any_org?: boolean; } // From codersdk/authorization.go +/** + * AuthorizationRequest is a structure instead of a map because + * go-playground/validate can only validate structs. If you attempt to pass + * a map into `httpapi.Read`, you will get an invalid type error. + */ export interface AuthorizationRequest { + /** + * Checks is a map keyed with an arbitrary string to a permission check. + * The key can be any string that is helpful to the caller, and allows + * multiple permission checks to be run in a single request. + * The key ensures that each permission check has the same key in the + * response. + */ readonly checks: Record; } @@ -718,6 +836,10 @@ export type AutomaticUpdates = "always" | "never"; export const AutomaticUpdateses: AutomaticUpdates[] = ["always", "never"]; // From codersdk/deployment.go +/** + * AvailableExperiments is an expandable type that returns all safe experiments + * available to be used with a deployment. + */ export interface AvailableExperiments { readonly safe: readonly Experiment[]; } @@ -730,6 +852,9 @@ export interface BannerConfig { } // From healthsdk/healthsdk.go +/** + * BaseReport holds fields common to various health reports. + */ export interface BaseReport { readonly error?: string; readonly severity: HealthSeverity; @@ -738,16 +863,51 @@ export interface BaseReport { } // From codersdk/deployment.go +/** + * BuildInfoResponse contains build information for this instance of Coder. + */ export interface BuildInfoResponse { + /** + * ExternalURL references the current Coder version. + * For production builds, this will link directly to a release. For development builds, this will link to a commit. + */ readonly external_url: string; + /** + * Version returns the semantic version of the build. + */ readonly version: string; + /** + * DashboardURL is the URL to hit the deployment's dashboard. + * For external workspace proxies, this is the coderd they are connected + * to. + */ readonly dashboard_url: string; + /** + * Telemetry is a boolean that indicates whether telemetry is enabled. + */ readonly telemetry: boolean; readonly workspace_proxy: boolean; + /** + * AgentAPIVersion is the current version of the Agent API (back versions + * MAY still be supported). + */ readonly agent_api_version: string; + /** + * ProvisionerAPIVersion is the current version of the Provisioner API + */ readonly provisioner_api_version: string; + /** + * UpgradeMessage is the message displayed to users when an outdated client + * is detected. + */ readonly upgrade_message: string; + /** + * DeploymentID is the unique identifier for this deployment. + */ readonly deployment_id: string; + /** + * WebPushPublicKey is the public key for push notifications via Web Push. + */ readonly webpush_public_key?: string; } @@ -776,12 +936,25 @@ export const BuildReasons: BuildReason[] = [ ]; // From codersdk/client.go +/** + * BuildVersionHeader contains build information of Coder. + */ export const BuildVersionHeader = "X-Coder-Build-Version"; // From codersdk/client.go +/** + * BypassRatelimitHeader is the custom header to use to bypass ratelimits. + * Only owners can bypass rate limits. This is typically used for scale testing. + * nolint: gosec + */ export const BypassRatelimitHeader = "X-Coder-Bypass-Ratelimit"; // From codersdk/client.go +/** + * CLITelemetryHeader contains a base64-encoded representation of the CLI + * command that was invoked to produce the request. It is for internal use + * only. + */ export const CLITelemetryHeader = "Coder-CLI-Telemetry"; // From codersdk/cors_behavior.go @@ -791,6 +964,9 @@ export const CORSBehaviors: CORSBehavior[] = ["passthru", "simple"]; // From codersdk/workspacebuilds.go export interface CancelWorkspaceBuildParams { + /** + * ExpectStatus ensures the build is in the expected status before canceling. + */ readonly expect_status?: CancelWorkspaceBuildStatus; } @@ -803,6 +979,9 @@ export const CancelWorkspaceBuildStatuses: CancelWorkspaceBuildStatus[] = [ ]; // From codersdk/users.go +/** + * ChangePasswordWithOneTimePasscodeRequest enables callers to change their password when they've forgotten it. + */ export interface ChangePasswordWithOneTimePasscodeRequest { readonly email: string; readonly password: string; @@ -810,9 +989,16 @@ export interface ChangePasswordWithOneTimePasscodeRequest { } // From codersdk/client.go +/** + * CoderDesktopTelemetryHeader contains a JSON-encoded representation of Desktop telemetry + * fields, including device ID, OS, and Desktop version. + */ export const CoderDesktopTelemetryHeader = "Coder-Desktop-Telemetry"; // From codersdk/insights.go +/** + * ConnectionLatency shows the latency for a connection. + */ export interface ConnectionLatency { readonly p50: number; readonly p95: number; @@ -830,7 +1016,19 @@ export interface ConnectionLog { readonly agent_name: string; readonly ip?: string; readonly type: ConnectionType; + /** + * WebInfo is only set when `type` is one of: + * - `ConnectionTypePortForwarding` + * - `ConnectionTypeWorkspaceApp` + */ readonly web_info?: ConnectionLogWebInfo; + /** + * SSHInfo is only set when `type` is one of: + * - `ConnectionTypeSSH` + * - `ConnectionTypeReconnectingPTY` + * - `ConnectionTypeVSCode` + * - `ConnectionTypeJetBrains` + */ readonly ssh_info?: ConnectionLogSSHInfo; } @@ -843,8 +1041,20 @@ export interface ConnectionLogResponse { // From codersdk/connectionlog.go export interface ConnectionLogSSHInfo { readonly connection_id: string; + /** + * DisconnectTime is omitted if a disconnect event with the same connection ID + * has not yet been seen. + */ readonly disconnect_time?: string; + /** + * DisconnectReason is omitted if a disconnect event with the same connection ID + * has not yet been seen. + */ readonly disconnect_reason?: string; + /** + * ExitCode is the exit code of the SSH session. It is omitted if a + * disconnect event with the same connection ID has not yet been seen. + */ readonly exit_code?: number; } @@ -859,8 +1069,14 @@ export const ConnectionLogStatuses: ConnectionLogStatus[] = [ // From codersdk/connectionlog.go export interface ConnectionLogWebInfo { readonly user_agent: string; + /** + * User is omitted if the connection event was from an unauthenticated user. + */ readonly user: User | null; readonly slug_or_port: string; + /** + * StatusCode is the HTTP status code of the request. + */ readonly status_code: number; } @@ -895,6 +1111,9 @@ export const ContentTypeZip = "application/zip"; // From codersdk/users.go export interface ConvertLoginRequest { + /** + * ToType is the login type to convert to. + */ readonly to_type: LoginType; readonly password: string; } @@ -910,6 +1129,9 @@ export interface CreateFirstUserRequest { } // From codersdk/users.go +/** + * CreateFirstUserResponse contains IDs for newly created user info. + */ export interface CreateFirstUserResponse { readonly user_id: string; readonly organization_id: string; @@ -937,6 +1159,9 @@ export interface CreateGroupRequest { // From codersdk/organizations.go export interface CreateOrganizationRequest { readonly name: string; + /** + * DisplayName will default to the same value as `Name` if not provided. + */ readonly display_name?: string; readonly description?: string; readonly icon?: string; @@ -954,6 +1179,11 @@ export interface CreateProvisionerKeyResponse { } // From codersdk/aitasks.go +/** + * CreateTaskRequest represents the request to create a new task. + * + * Experimental: This type is experimental and may change in the future. + */ export interface CreateTaskRequest { readonly template_version_id: string; readonly template_version_preset_id?: string; @@ -962,30 +1192,127 @@ export interface CreateTaskRequest { } // From codersdk/organizations.go +/** + * CreateTemplateRequest provides options when creating a template. + */ export interface CreateTemplateRequest { + /** + * Name is the name of the template. + */ readonly name: string; + /** + * DisplayName is the displayed name of the template. + */ readonly display_name?: string; + /** + * Description is a description of what the template contains. It must be + * less than 128 bytes. + */ readonly description?: string; + /** + * Icon is a relative path or external URL that specifies + * an icon to be displayed in the dashboard. + */ readonly icon?: string; + /** + * VersionID is an in-progress or completed job to use as an initial version + * of the template. + * + * This is required on creation to enable a user-flow of validating a + * template works. There is no reason the data-model cannot support empty + * templates, but it doesn't make sense for users. + */ readonly template_version_id: string; + /** + * DefaultTTLMillis allows optionally specifying the default TTL + * for all workspaces created from this template. + */ readonly default_ttl_ms?: number; + /** + * ActivityBumpMillis allows optionally specifying the activity bump + * duration for all workspaces created from this template. Defaults to 1h + * but can be set to 0 to disable activity bumping. + */ readonly activity_bump_ms?: number; + /** + * AutostopRequirement allows optionally specifying the autostop requirement + * for workspaces created from this template. This is an enterprise feature. + */ readonly autostop_requirement?: TemplateAutostopRequirement; + /** + * AutostartRequirement allows optionally specifying the autostart allowed days + * for workspaces created from this template. This is an enterprise feature. + */ readonly autostart_requirement?: TemplateAutostartRequirement; + /** + * Allow users to cancel in-progress workspace jobs. + * *bool as the default value is "true". + */ readonly allow_user_cancel_workspace_jobs: boolean | null; + /** + * AllowUserAutostart allows users to set a schedule for autostarting their + * workspace. By default this is true. This can only be disabled when using + * an enterprise license. + */ readonly allow_user_autostart?: boolean; + /** + * AllowUserAutostop allows users to set a custom workspace TTL to use in + * place of the template's DefaultTTL field. By default this is true. If + * false, the DefaultTTL will always be used. This can only be disabled when + * using an enterprise license. + */ readonly allow_user_autostop?: boolean; + /** + * FailureTTLMillis allows optionally specifying the max lifetime before Coder + * stops all resources for failed workspaces created from this template. + */ readonly failure_ttl_ms?: number; + /** + * TimeTilDormantMillis allows optionally specifying the max lifetime before Coder + * locks inactive workspaces created from this template. + */ readonly dormant_ttl_ms?: number; + /** + * TimeTilDormantAutoDeleteMillis allows optionally specifying the max lifetime before Coder + * permanently deletes dormant workspaces created from this template. + */ readonly delete_ttl_ms?: number; + /** + * DisableEveryoneGroupAccess allows optionally disabling the default + * behavior of granting the 'everyone' group access to use the template. + * If this is set to true, the template will not be available to all users, + * and must be explicitly granted to users or groups in the permissions settings + * of the template. + */ readonly disable_everyone_group_access: boolean; + /** + * RequireActiveVersion mandates that workspaces are built with the active + * template version. + */ readonly require_active_version: boolean; + /** + * MaxPortShareLevel allows optionally specifying the maximum port share level + * for workspaces created from the template. + */ readonly max_port_share_level: WorkspaceAgentPortShareLevel | null; + /** + * UseClassicParameterFlow allows optionally specifying whether + * the template should use the classic parameter flow. The default if unset is + * true, and is why `*bool` is used here. When dynamic parameters becomes + * the default, this will default to false. + */ readonly template_use_classic_parameter_flow?: boolean; + /** + * CORSBehavior allows optionally specifying the CORS behavior for all shared ports. + */ readonly cors_behavior: CORSBehavior | null; } // From codersdk/templateversions.go +/** + * CreateTemplateVersionDryRunRequest defines the request parameters for + * CreateTemplateVersionDryRun. + */ export interface CreateTemplateVersionDryRunRequest { readonly workspace_name: string; readonly rich_parameter_values: readonly WorkspaceBuildParameter[]; @@ -993,9 +1320,15 @@ export interface CreateTemplateVersionDryRunRequest { } // From codersdk/organizations.go +/** + * CreateTemplateVersionRequest enables callers to create a new Template Version. + */ export interface CreateTemplateVersionRequest { readonly name?: string; readonly message?: string; + /** + * TemplateID optionally associates a version with a template. + */ readonly template_id?: string; readonly storage_method: ProvisionerStorageMethod; readonly file_id?: string; @@ -1020,7 +1353,7 @@ export interface CreateTestAuditLogRequest { // From codersdk/apikey.go export interface CreateTokenRequest { readonly lifetime: number; - readonly scope?: APIKeyScope; + readonly scope?: APIKeyScope; // Deprecated: use Scopes instead. readonly scopes?: readonly APIKeyScope[]; readonly token_name: string; readonly allow_list?: readonly APIAllowListTarget[]; @@ -1032,8 +1365,17 @@ export interface CreateUserRequestWithOrgs { readonly username: string; readonly name: string; readonly password: string; + /** + * UserLoginType defaults to LoginTypePassword. + */ readonly login_type: LoginType; + /** + * UserStatus defaults to UserStatusDormant. + */ readonly user_status: UserStatus | null; + /** + * OrganizationIDs is a list of organization IDs that the user should be a member of. + */ readonly organization_ids: readonly string[]; } @@ -1054,15 +1396,35 @@ export const CreateWorkspaceBuildReasons: CreateWorkspaceBuildReason[] = [ ]; // From codersdk/workspaces.go +/** + * CreateWorkspaceBuildRequest provides options to update the latest workspace build. + */ export interface CreateWorkspaceBuildRequest { readonly template_version_id?: string; readonly transition: WorkspaceTransition; readonly dry_run?: boolean; readonly state?: string; + /** + * Orphan may be set for the Destroy transition. + */ readonly orphan?: boolean; + /** + * ParameterValues are optional. It will write params to the 'workspace' scope. + * This will overwrite any existing parameters with the same name. + * This will not delete old params not included in this list. + */ readonly rich_parameter_values?: readonly WorkspaceBuildParameter[]; + /** + * Log level changes the default logging verbosity of a provider ("info" if empty). + */ readonly log_level?: ProvisionerLogLevel; + /** + * TemplateVersionPresetID is the ID of the template version preset to use for the build. + */ readonly template_version_preset_id?: string; + /** + * Reason sets the reason for the workspace build. + */ readonly reason?: CreateWorkspaceBuildReason; } @@ -1074,12 +1436,36 @@ export interface CreateWorkspaceProxyRequest { } // From codersdk/organizations.go +/** + * CreateWorkspaceRequest provides options for creating a new workspace. + * Either TemplateID or TemplateVersionID must be specified. They cannot both be present. + * @Description CreateWorkspaceRequest provides options for creating a new workspace. + * @Description Only one of TemplateID or TemplateVersionID can be specified, not both. + * @Description If TemplateID is specified, the active version of the template will be used. + * @Description Workspace names: + * @Description - Must start with a letter or number + * @Description - Can only contain letters, numbers, and hyphens + * @Description - Cannot contain spaces or special characters + * @Description - Cannot be named `new` or `create` + * @Description - Must be unique within your workspaces + * @Description - Maximum length of 32 characters + */ export interface CreateWorkspaceRequest { + /** + * TemplateID specifies which template should be used for creating the workspace. + */ readonly template_id?: string; + /** + * TemplateVersionID can be used to specify a specific version of a template for creating the workspace. + */ readonly template_version_id?: string; readonly name: string; readonly autostart_schedule?: string; readonly ttl_ms?: number; + /** + * RichParameterValues allows for additional parameters to be provided + * during the initial provision. + */ readonly rich_parameter_values?: readonly WorkspaceBuildParameter[]; readonly automatic_updates?: AutomaticUpdates; readonly template_version_preset_id?: string; @@ -1120,16 +1506,26 @@ export interface CustomNotificationRequest { } // From codersdk/roles.go +/** + * CustomRoleRequest is used to edit custom roles. + */ export interface CustomRoleRequest { readonly name: string; readonly display_name: string; readonly site_permissions: readonly Permission[]; + /** + * OrganizationPermissions are specific to the organization the role belongs to. + */ readonly organization_permissions: readonly Permission[]; readonly user_permissions: readonly Permission[]; } // From codersdk/deployment.go export interface DAUEntry { + /** + * Date is a string formatted as 2024-01-31. + * Timezone and time information is not included. + */ readonly date: string; readonly amount: number; } @@ -1160,7 +1556,13 @@ export interface DERPConfig { } // From healthsdk/healthsdk.go +/** + * DERPHealthReport includes health details of each configured DERP/STUN region. + */ export interface DERPHealthReport extends BaseReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly regions: Record; readonly netcheck?: NetcheckReport; @@ -1169,7 +1571,13 @@ export interface DERPHealthReport extends BaseReport { } // From healthsdk/healthsdk.go +/** + * DERPHealthReport includes health details of a single node in a single region. + */ export interface DERPNodeReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly severity: HealthSeverity; readonly warnings: readonly HealthMessage[]; @@ -1192,7 +1600,13 @@ export interface DERPRegion { } // From healthsdk/healthsdk.go +/** + * DERPHealthReport includes health details of each node in a single region. + */ export interface DERPRegionReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly severity: HealthSeverity; readonly warnings: readonly HealthMessage[]; @@ -1222,7 +1636,13 @@ export interface DangerousConfig { export const DatabaseNotReachable = "database not reachable"; // From healthsdk/healthsdk.go +/** + * DatabaseReport shows the results of pinging the configured database.Conn. + */ export interface DatabaseReport extends BaseReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly reachable: boolean; readonly latency: string; @@ -1232,6 +1652,9 @@ export interface DatabaseReport extends BaseReport { // From codersdk/externalauth.go export interface DeleteExternalAuthByIDResponse { + /** + * TokenRevoked set to true if token revocation was attempted and was successful + */ readonly token_revoked: boolean; readonly token_revocation_error?: string; } @@ -1248,6 +1671,9 @@ export interface DeleteWorkspaceAgentPortShareRequest { } // From codersdk/deployment.go +/** + * DeploymentConfig contains both the deployment values and how they're set. + */ export interface DeploymentConfig { readonly config?: DeploymentValues; readonly options?: SerpentOptionSet; @@ -1255,20 +1681,37 @@ export interface DeploymentConfig { // From codersdk/deployment.go export interface DeploymentStats { + /** + * AggregatedFrom is the time in which stats are aggregated from. + * This might be back in time a specific duration or interval. + */ readonly aggregated_from: string; + /** + * CollectedAt is the time in which stats are collected at. + */ readonly collected_at: string; + /** + * NextUpdateAt is the time when the next batch of stats will + * be updated. + */ readonly next_update_at: string; readonly workspaces: WorkspaceDeploymentStats; readonly session_count: SessionCountDeploymentStats; } // From codersdk/deployment.go +/** + * DeploymentValues is the central configuration values the coder server. + */ export interface DeploymentValues { readonly verbose?: boolean; readonly access_url?: string; readonly wildcard_access_url?: string; readonly docs_url?: string; readonly redirect_to_access_url?: boolean; + /** + * HTTPAddress is a string because it may be set to zero to disable. + */ readonly http_address?: string; readonly autobuild_poll_interval?: number; readonly job_hang_detector_interval?: number; @@ -1327,6 +1770,9 @@ export interface DeploymentValues { readonly ai?: AIConfig; readonly config?: string; readonly write_config?: boolean; + /** + * Deprecated: Use HTTPAddress or TLS.Address instead. + */ readonly address?: string; } @@ -1361,8 +1807,15 @@ export const DisplayApps: DisplayApp[] = [ // From codersdk/parameters.go export interface DynamicParametersRequest { + /** + * ID identifies the request. The response contains the same + * ID so that the client can match it to the request. + */ readonly id: number; readonly inputs: Record; + /** + * OwnerID if uuid.Nil, it defaults to `codersdk.Me` + */ readonly owner_id?: string; } @@ -1412,6 +1865,9 @@ export interface Entitlements { } // From codersdk/client.go +/** + * EntitlementsWarnings contains active warnings for the user's entitlements. + */ export const EntitlementsWarningHeader = "X-Coder-Entitlements-Warning"; // From codersdk/deployment.go @@ -1444,6 +1900,9 @@ export interface ExternalAPIKeyScopes { } // From codersdk/workspaces.go +/** + * ExternalAgentCredentials contains the credentials needed for an external agent to connect to Coder. + */ export interface ExternalAgentCredentials { readonly command: string; readonly agent_token: string; @@ -1455,9 +1914,21 @@ export interface ExternalAuth { readonly device: boolean; readonly display_name: string; readonly supports_revocation: boolean; + /** + * User is the user that authenticated with the provider. + */ readonly user: ExternalAuthUser | null; + /** + * AppInstallable is true if the request for app installs was successful. + */ readonly app_installable: boolean; + /** + * AppInstallations are the installations that the user has access to. + */ readonly installations: readonly ExternalAuthAppInstallation[]; + /** + * AppInstallURL is the URL to install the app. + */ readonly app_install_url: string; } @@ -1470,8 +1941,15 @@ export interface ExternalAuthAppInstallation { // From codersdk/deployment.go export interface ExternalAuthConfig { + /** + * Type is the type of external auth config. + */ readonly type: string; readonly client_id: string; + /** + * ID is a unique identifier for the auth config. + * It defaults to `type` when not provided. + */ readonly id: string; readonly auth_url: string; readonly token_url: string; @@ -1486,12 +1964,30 @@ export interface ExternalAuthConfig { readonly mcp_url: string; readonly mcp_tool_allow_regex: string; readonly mcp_tool_deny_regex: string; + /** + * Regex allows API requesters to match an auth config by + * a string (e.g. coder.com) instead of by it's type. + * + * Git clone makes use of this by parsing the URL from: + * 'Username for "https://github.com":' + * And sending it to the Coder server to match against the Regex. + */ readonly regex: string; + /** + * DisplayName is shown in the UI to identify the auth config. + */ readonly display_name: string; + /** + * DisplayIcon is a URL to an icon to display in the UI. + */ readonly display_icon: string; } // From codersdk/externalauth.go +/** + * ExternalAuthDevice is the response from the device authorization endpoint. + * See: https://tools.ietf.org/html/rfc8628#section-3.2 + */ export interface ExternalAuthDevice { readonly device_code: string; readonly user_code: string; @@ -1506,6 +2002,11 @@ export interface ExternalAuthDeviceExchange { } // From codersdk/externalauth.go +/** + * ExternalAuthLink is a link between a user and an external auth provider. + * It excludes information that requires a token to access, so can be statically + * built from the database and configs. + */ export interface ExternalAuthLink { readonly provider_id: string; readonly created_at: string; @@ -1517,6 +2018,9 @@ export interface ExternalAuthLink { } // From codersdk/externalauth.go +/** + * ExternalAuthLinkProvider are the static details of a provider. + */ export interface ExternalAuthLinkProvider { readonly id: string; readonly type: string; @@ -1543,7 +2047,23 @@ export interface Feature { readonly enabled: boolean; readonly limit?: number; readonly actual?: number; + /** + * SoftLimit is the soft limit of the feature, and is only used for showing + * included limits in the dashboard. No license validation or warnings are + * generated from this value. + */ readonly soft_limit?: number; + /** + * UsagePeriod denotes that the usage is a counter that accumulates over + * this period (and most likely resets with the issuance of the next + * license). + * + * These dates are determined from the license that this entitlement comes + * from, see enterprise/coderd/license/license.go. + * + * Only certain features set these fields: + * - FeatureManagedAgentLimit + */ readonly usage_period?: UsagePeriod; } @@ -1608,6 +2128,10 @@ export const FeatureSets: FeatureSet[] = ["enterprise", "", "premium"]; export const FormatZip = "zip"; // From codersdk/parameters.go +/** + * FriendlyDiagnostic == previewtypes.FriendlyDiagnostic + * Copied to avoid import deps + */ export interface FriendlyDiagnostic { readonly severity: DiagnosticSeverityString; readonly summary: string; @@ -1616,6 +2140,9 @@ export interface FriendlyDiagnostic { } // From codersdk/apikey.go +/** + * GenerateAPIKeyResponse contains an API key for a user. + */ export interface GenerateAPIKeyResponse { readonly key: string; } @@ -1647,6 +2174,11 @@ export interface GitSSHKey { readonly user_id: string; readonly created_at: string; readonly updated_at: string; + /** + * PublicKey is the SSH public key in OpenSSH format. + * Example: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID3OmYJvT7q1cF1azbybYy0OZ9yrXfA+M6Lr4vzX5zlp\n" + * Note: The key includes a trailing newline (\n). + */ readonly public_key: string; } @@ -1663,6 +2195,11 @@ export interface Group { readonly display_name: string; readonly organization_id: string; readonly members: readonly ReducedUser[]; + /** + * How many members are in this group. Shows the total count, + * even if the user is not authorized to read group member details. + * May be greater than `len(Group.Members)`. + */ readonly total_member_count: number; readonly avatar_url: string; readonly quota_allowance: number; @@ -1673,8 +2210,18 @@ export interface Group { // From codersdk/groups.go export interface GroupArguments { + /** + * Organization can be an org UUID or name + */ readonly Organization: string; + /** + * HasMember can be a user uuid or username + */ readonly HasMember: string; + /** + * GroupIDs is a list of group UUIDs to filter by. + * If not set, all groups will be returned. + */ readonly GroupIDs: readonly string[]; } @@ -1685,10 +2232,33 @@ export const GroupSources: GroupSource[] = ["oidc", "user"]; // From codersdk/idpsync.go export interface GroupSyncSettings { + /** + * Field is the name of the claim field that specifies what groups a user + * should be in. If empty, no groups will be synced. + */ readonly field: string; + /** + * Mapping is a map from OIDC groups to Coder group IDs + */ readonly mapping: Record; + /** + * RegexFilter is a regular expression that filters the groups returned by + * the OIDC provider. Any group not matched by this regex will be ignored. + * If the group filter is nil, then no group filtering will occur. + */ readonly regex_filter: string | null; + /** + * AutoCreateMissing controls whether groups returned by the OIDC provider + * are automatically created in Coder if they are missing. + */ readonly auto_create_missing_groups: boolean; + /** + * LegacyNameMapping is deprecated. It remaps an IDP group name to + * a Coder group name. Since configuration is now done at runtime, + * group IDs are used to account for group renames. + * For legacy configurations, this config option has to remain. + * Deprecated: Use Mapping instead. + */ readonly legacy_group_name_mapping?: Record; } @@ -1750,6 +2320,9 @@ export const HealthCodes: HealthCode[] = [ ]; // From health/model.go +/** + * @typescript-generate Message + */ export interface HealthMessage { readonly code: HealthCode; readonly message: string; @@ -1785,21 +2358,46 @@ export const HealthSeveritys: HealthSeverity[] = ["error", "ok", "warning"]; // From codersdk/workspaceapps.go export interface Healthcheck { + /** + * URL specifies the endpoint to check for the app health. + */ readonly url: string; + /** + * Interval specifies the seconds between each health check. + */ readonly interval: number; + /** + * Threshold specifies the number of consecutive failed health checks before returning "unhealthy". + */ readonly threshold: number; } // From codersdk/deployment.go +/** + * HealthcheckConfig contains configuration for healthchecks. + */ export interface HealthcheckConfig { readonly refresh: number; readonly threshold_database: number; } // From healthsdk/healthsdk.go +/** + * HealthcheckReport contains information about the health status of a Coder deployment. + */ export interface HealthcheckReport { + /** + * Time is the time the report was generated at. + */ readonly time: string; + /** + * Healthy is true if the report returns no errors. + * Deprecated: use `Severity` instead + */ readonly healthy: boolean; + /** + * Severity indicates the status of Coder health. + */ readonly severity: HealthSeverity; readonly derp: DERPHealthReport; readonly access_url: AccessURLReport; @@ -1807,12 +2405,21 @@ export interface HealthcheckReport { readonly database: DatabaseReport; readonly workspace_proxy: WorkspaceProxyReport; readonly provisioner_daemons: ProvisionerDaemonsReport; + /** + * The Coder version of the server that the report was generated on. + */ readonly coder_version: string; } // From codersdk/idpsync.go export interface IDPSyncMapping { + /** + * The IdP claim the user has + */ readonly Given: string; + /** + * The ID of the Coder resource the user should be added to + */ readonly Gets: ResourceIdType; } @@ -1858,6 +2465,9 @@ export const InsightsReportIntervals: InsightsReportInterval[] = [ // From codersdk/workspaceagents.go export interface IssueReconnectingPTYSignedTokenRequest { + /** + * URL is the URL of the reconnecting-pty endpoint you are connecting to. + */ readonly url: string; readonly agentID: string; } @@ -1877,6 +2487,12 @@ export interface License { readonly id: number; readonly uuid: string; readonly uploaded_at: string; + /** + * Claims are the JWT claims asserted by the license. Here we use + * a generic string map to ensure that all data from the server is + * parsed verbatim, not just the fields this version of Coder + * understands. + */ // empty interface{} type, falling back to unknown readonly claims: Record; } @@ -1912,6 +2528,12 @@ export interface ListInboxNotificationsResponse { // From codersdk/externalauth.go export interface ListUserExternalAuthResponse { readonly providers: readonly ExternalAuthLinkProvider[]; + /** + * Links are all the authenticated links for the user. + * If a link has a provider ID that does not exist, then that provider + * is no longer configured, rendering it unusable. It is still valuable + * to include these links so that the user can unlink them. + */ readonly links: readonly ExternalAuthLink[]; } @@ -1952,20 +2574,45 @@ export const LoginTypes: LoginType[] = [ ]; // From codersdk/users.go +/** + * LoginWithPasswordRequest enables callers to authenticate with email and password. + */ export interface LoginWithPasswordRequest { readonly email: string; readonly password: string; } // From codersdk/users.go +/** + * LoginWithPasswordResponse contains a session token for the newly authenticated user. + */ export interface LoginWithPasswordResponse { readonly session_token: string; } // From codersdk/provisionerdaemons.go +/** + * MatchedProvisioners represents the number of provisioner daemons + * available to take a job at a specific point in time. + * Introduced in Coder version 2.18.0. + */ export interface MatchedProvisioners { + /** + * Count is the number of provisioner daemons that matched the given + * tags. If the count is 0, it means no provisioner daemons matched the + * requested tags. + */ readonly count: number; + /** + * Available is the number of provisioner daemons that are available to + * take jobs. This may be less than the count if some provisioners are + * busy or have been stopped. + */ readonly available: number; + /** + * MostRecentlySeen is the most recently seen time of the set of matched + * provisioners. If no provisioners matched, this field will be null. + */ readonly most_recently_seen?: string; } @@ -1978,6 +2625,10 @@ export interface MinimalOrganization { } // From codersdk/users.go +/** + * MinimalUser is the minimal information needed to identify a user and show + * them on the UI. + */ export interface MinimalUser { readonly id: string; readonly username: string; @@ -1985,25 +2636,53 @@ export interface MinimalUser { } // From netcheck/netcheck.go +/** + * Report contains the result of a single netcheck. + */ export interface NetcheckReport { - readonly UDP: boolean; - readonly IPv6: boolean; - readonly IPv4: boolean; - readonly IPv6CanSend: boolean; - readonly IPv4CanSend: boolean; - readonly OSHasIPv6: boolean; - readonly ICMPv4: boolean; + readonly UDP: boolean; // a UDP STUN round trip completed + readonly IPv6: boolean; // an IPv6 STUN round trip completed + readonly IPv4: boolean; // an IPv4 STUN round trip completed + readonly IPv6CanSend: boolean; // an IPv6 packet was able to be sent + readonly IPv4CanSend: boolean; // an IPv4 packet was able to be sent + readonly OSHasIPv6: boolean; // could bind a socket to ::1 + readonly ICMPv4: boolean; // an ICMPv4 round trip completed + /** + * MappingVariesByDestIP is whether STUN results depend which + * STUN server you're talking to (on IPv4). + */ readonly MappingVariesByDestIP: boolean | null; + /** + * HairPinning is whether the router supports communicating + * between two local devices through the NATted public IP address + * (on IPv4). + */ readonly HairPinning: boolean | null; + /** + * UPnP is whether UPnP appears present on the LAN. + * Empty means not checked. + */ readonly UPnP: boolean | null; + /** + * PMP is whether NAT-PMP appears present on the LAN. + * Empty means not checked. + */ readonly PMP: boolean | null; + /** + * PCP is whether PCP appears present on the LAN. + * Empty means not checked. + */ readonly PCP: boolean | null; - readonly PreferredDERP: number; - readonly RegionLatency: Record; - readonly RegionV4Latency: Record; - readonly RegionV6Latency: Record; - readonly GlobalV4: string; - readonly GlobalV6: string; + readonly PreferredDERP: number; // or 0 for unknown + readonly RegionLatency: Record; // keyed by DERP Region ID + readonly RegionV4Latency: Record; // keyed by DERP Region ID + readonly RegionV6Latency: Record; // keyed by DERP Region ID + readonly GlobalV4: string; // ip:port of global IPv4 + readonly GlobalV6: string; // [ip]:port of global IPv6 + /** + * CaptivePortal is set when we think there's a captive portal that is + * intercepting HTTP traffic. + */ readonly CaptivePortal: boolean | null; } @@ -2035,45 +2714,139 @@ export interface NotificationTemplate { // From codersdk/deployment.go export interface NotificationsConfig { + /** + * The upper limit of attempts to send a notification. + */ readonly max_send_attempts: number; + /** + * The minimum time between retries. + */ readonly retry_interval: number; + /** + * The notifications system buffers message updates in memory to ease pressure on the database. + * This option controls how often it synchronizes its state with the database. The shorter this value the + * lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the + * database. It is recommended to keep this option at its default value. + */ readonly sync_interval: number; + /** + * The notifications system buffers message updates in memory to ease pressure on the database. + * This option controls how many updates are kept in memory. The lower this value the + * lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the + * database. It is recommended to keep this option at its default value. + */ readonly sync_buffer_size: number; + /** + * How long a notifier should lease a message. This is effectively how long a notification is 'owned' + * by a notifier, and once this period expires it will be available for lease by another notifier. Leasing + * is important in order for multiple running notifiers to not pick the same messages to deliver concurrently. + * This lease period will only expire if a notifier shuts down ungracefully; a dispatch of the notification + * releases the lease. + */ readonly lease_period: number; + /** + * How many notifications a notifier should lease per fetch interval. + */ readonly lease_count: number; + /** + * How often to query the database for queued notifications. + */ readonly fetch_interval: number; + /** + * Which delivery method to use (available options: 'smtp', 'webhook'). + */ readonly method: string; + /** + * How long to wait while a notification is being sent before giving up. + */ readonly dispatch_timeout: number; + /** + * SMTP settings. + */ readonly email: NotificationsEmailConfig; + /** + * Webhook settings. + */ readonly webhook: NotificationsWebhookConfig; + /** + * Inbox settings. + */ readonly inbox: NotificationsInboxConfig; } // From codersdk/deployment.go export interface NotificationsEmailAuthConfig { + /** + * Identity for PLAIN auth. + */ readonly identity: string; + /** + * Username for LOGIN/PLAIN auth. + */ readonly username: string; + /** + * Password for LOGIN/PLAIN auth. + */ readonly password: string; + /** + * File from which to load the password for LOGIN/PLAIN auth. + */ readonly password_file: string; } // From codersdk/deployment.go export interface NotificationsEmailConfig { + /** + * The sender's address. + */ readonly from: string; + /** + * The intermediary SMTP host through which emails are sent (host:port). + */ readonly smarthost: string; + /** + * The hostname identifying the SMTP server. + */ readonly hello: string; + /** + * Authentication details. + */ readonly auth: NotificationsEmailAuthConfig; + /** + * TLS details. + */ readonly tls: NotificationsEmailTLSConfig; + /** + * ForceTLS causes a TLS connection to be attempted. + */ readonly force_tls: boolean; } // From codersdk/deployment.go export interface NotificationsEmailTLSConfig { + /** + * StartTLS attempts to upgrade plain connections to TLS. + */ readonly start_tls: boolean; + /** + * ServerName to verify the hostname for the targets. + */ readonly server_name: string; + /** + * InsecureSkipVerify skips target certificate validation. + */ readonly insecure_skip_verify: boolean; + /** + * CAFile specifies the location of the CA certificate to use. + */ readonly ca_file: string; + /** + * CertFile specifies the location of the certificate to use. + */ readonly cert_file: string; + /** + * KeyFile specifies the location of the key to use. + */ readonly key_file: string; } @@ -2089,10 +2862,16 @@ export interface NotificationsSettings { // From codersdk/deployment.go export interface NotificationsWebhookConfig { + /** + * The URL to which the payload will be sent with an HTTP POST request. + */ readonly endpoint: string; } // From codersdk/parameters.go +/** + * NullHCLString == `previewtypes.NullHCLString`. + */ export interface NullHCLString { readonly value: string; readonly valid: boolean; @@ -2102,10 +2881,16 @@ export interface NullHCLString { export interface OAuth2AppEndpoints { readonly authorization: string; readonly token: string; + /** + * DeviceAuth is optional. + */ readonly device_authorization: string; } // From codersdk/oauth2.go +/** + * OAuth2AuthorizationServerMetadata represents RFC 8414 OAuth 2.0 Authorization Server Metadata + */ export interface OAuth2AuthorizationServerMetadata { readonly issuer: string; readonly authorization_endpoint: string; @@ -2119,6 +2904,10 @@ export interface OAuth2AuthorizationServerMetadata { } // From codersdk/oauth2.go +/** + * OAuth2ClientConfiguration represents RFC 7592 Client Configuration (for GET/PUT operations) + * Same as OAuth2ClientRegistrationResponse but without client_secret in GET responses + */ export interface OAuth2ClientConfiguration { readonly client_id: string; readonly client_id_issued_at: number; @@ -2143,6 +2932,9 @@ export interface OAuth2ClientConfiguration { } // From codersdk/oauth2.go +/** + * OAuth2ClientRegistrationRequest represents RFC 7591 Dynamic Client Registration Request + */ export interface OAuth2ClientRegistrationRequest { readonly redirect_uris?: readonly string[]; readonly client_name?: string; @@ -2163,6 +2955,9 @@ export interface OAuth2ClientRegistrationRequest { } // From codersdk/oauth2.go +/** + * OAuth2ClientRegistrationResponse represents RFC 7591 Dynamic Client Registration Response + */ export interface OAuth2ClientRegistrationResponse { readonly client_id: string; readonly client_secret?: string; @@ -2211,6 +3006,9 @@ export interface OAuth2GithubConfig { } // From codersdk/oauth2.go +/** + * OAuth2ProtectedResourceMetadata represents RFC 9728 OAuth 2.0 Protected Resource Metadata + */ export interface OAuth2ProtectedResourceMetadata { readonly resource: string; readonly authorization_servers: readonly string[]; @@ -2224,6 +3022,11 @@ export interface OAuth2ProviderApp { readonly name: string; readonly callback_url: string; readonly icon: string; + /** + * Endpoints are included in the app response for easier discovery. The OAuth2 + * spec does not have a defined place to find these (for comparison, OIDC has + * a '/.well-known/openid-configuration' endpoint). + */ readonly endpoints: OAuth2AppEndpoints; } @@ -2261,9 +3064,15 @@ export const OAuth2ProviderResponseTypes: OAuth2ProviderResponseType[] = [ ]; // From codersdk/client.go +/** + * OAuth2RedirectCookie is the name of the cookie that stores the oauth2 redirect. + */ export const OAuth2RedirectCookie = "oauth_redirect"; // From codersdk/client.go +/** + * OAuth2StateCookie is the name of the cookie that stores the oauth2 state. + */ export const OAuth2StateCookie = "oauth_state"; // From codersdk/users.go @@ -2285,6 +3094,9 @@ export interface OIDCConfig { readonly allow_signups: boolean; readonly client_id: string; readonly client_secret: string; + /** + * ClientKeyFile & ClientCertFile are used in place of ClientSecret for PKI auth. + */ readonly client_key_file: string; readonly client_cert_file: string; readonly email_domain: string; @@ -2295,7 +3107,20 @@ export interface OIDCConfig { readonly name_field: string; readonly email_field: string; readonly auth_url_params: SerpentStruct>; + /** + * IgnoreUserInfo & UserInfoFromAccessToken are mutually exclusive. Only 1 + * can be set to true. Ideally this would be an enum with 3 states, ['none', + * 'userinfo', 'access_token']. However, for backward compatibility, + * `ignore_user_info` must remain. And `access_token` is a niche, non-spec + * compliant edge case. So it's use is rare, and should not be advised. + */ readonly ignore_user_info: boolean; + /** + * UserInfoFromAccessToken as mentioned above is an edge case. This allows + * sourcing the user_info from the access token itself instead of a user_info + * endpoint. This assumes the access token is a valid JWT with a set of claims to + * be merged with the id_token. + */ readonly source_user_info_from_access_token: boolean; readonly organization_field: string; readonly organization_mapping: SerpentStruct>; @@ -2325,6 +3150,9 @@ export const OptionTypes: OptionType[] = [ ]; // From codersdk/organizations.go +/** + * Organization is the JSON representation of a Coder organization. + */ export interface Organization extends MinimalOrganization { readonly description: string; readonly created_at: string; @@ -2378,8 +3206,20 @@ export interface OrganizationProvisionerJobsOptions { // From codersdk/idpsync.go export interface OrganizationSyncSettings { + /** + * Field selects the claim field to be used as the created user's + * organizations. If the field is the empty string, then no organization + * updates will ever come from the OIDC provider. + */ readonly field: string; + /** + * Mapping maps from an OIDC claim --> Coder organization uuid + */ readonly mapping: Record; + /** + * AssignDefault will ensure the default org is always included + * for every user, regardless of their claims. This preserves legacy behavior. + */ readonly organization_assign_default: boolean; } @@ -2396,9 +3236,30 @@ export interface PaginatedMembersResponse { } // From codersdk/pagination.go +/** + * Pagination sets pagination options for the endpoints that support it. + */ export interface Pagination { + /** + * AfterID returns all or up to Limit results after the given + * UUID. This option can be used with or as an alternative to + * Offset for better performance. To use it as an alternative, + * set AfterID to the last UUID returned by the previous + * request. + */ readonly after_id?: string; + /** + * Limit sets the maximum number of users to be returned + * in a single page. If the limit is <= 0, there is no limit + * and all users are returned. + */ readonly limit?: number; + /** + * Offset is used to indicate which page to return. An offset of 0 + * returns the first 'limit' number of users. + * To get the next page, use offset=*. + * Offset is 0 indexed, so the first record sits at offset 0. + */ readonly offset?: number; } @@ -2438,6 +3299,9 @@ export interface PatchGroupIDPSyncConfigRequest { } // From codersdk/idpsync.go +/** + * If the same mapping is present in both Add and Remove, Remove will take presidence. + */ export interface PatchGroupIDPSyncMappingRequest { readonly Add: readonly IDPSyncMapping[]; readonly Remove: readonly IDPSyncMapping[]; @@ -2460,6 +3324,9 @@ export interface PatchOrganizationIDPSyncConfigRequest { } // From codersdk/idpsync.go +/** + * If the same mapping is present in both Add and Remove, Remove will take presidence. + */ export interface PatchOrganizationIDPSyncMappingRequest { readonly Add: readonly IDPSyncMapping[]; readonly Remove: readonly IDPSyncMapping[]; @@ -2471,6 +3338,9 @@ export interface PatchRoleIDPSyncConfigRequest { } // From codersdk/idpsync.go +/** + * If the same mapping is present in both Add and Remove, Remove will take presidence. + */ export interface PatchRoleIDPSyncMappingRequest { readonly Add: readonly IDPSyncMapping[]; readonly Remove: readonly IDPSyncMapping[]; @@ -2492,10 +3362,21 @@ export interface PatchWorkspaceProxy { } // From codersdk/client.go +/** + * PathAppSessionTokenCookie is the name of the cookie that stores an + * application-scoped API token on workspace proxy path app domains. + *nolint:gosec + */ export const PathAppSessionTokenCookie = "coder_path_app_session_token"; // From codersdk/roles.go +/** + * Permission is the format passed into the rego. + */ export interface Permission { + /** + * Negate makes this a negative permission + */ readonly negate: boolean; readonly resource_type: RBACResource; readonly action: RBACAction; @@ -2527,9 +3408,26 @@ export interface PprofConfig { // From codersdk/deployment.go export interface PrebuildsConfig { + /** + * ReconciliationInterval defines how often the workspace prebuilds state should be reconciled. + */ readonly reconciliation_interval: number; + /** + * ReconciliationBackoffInterval specifies the amount of time to increase the backoff interval + * when errors occur during reconciliation. + */ readonly reconciliation_backoff_interval: number; + /** + * ReconciliationBackoffLookback determines the time window to look back when calculating + * the number of failed prebuilds, which influences the backoff strategy. + */ readonly reconciliation_backoff_lookback: number; + /** + * FailureHardLimit defines the maximum number of consecutive failed prebuild attempts allowed + * before a preset is considered to be in a hard limit state. When a preset hits this limit, + * no new prebuilds will be created until the limit is reset. + * FailureHardLimit is disabled when set to zero. + */ readonly failure_hard_limit: number; } @@ -2575,6 +3473,9 @@ export interface PreviewParameterData { readonly options: readonly PreviewParameterOption[]; readonly validations: readonly PreviewParameterValidation[]; readonly required: boolean; + /** + * legacy_variable_name was removed (= 14) + */ readonly order: number; readonly ephemeral: boolean; } @@ -2598,6 +3499,9 @@ export interface PreviewParameterStyling { // From codersdk/parameters.go export interface PreviewParameterValidation { readonly validation_error: string; + /** + * All validation attributes are optional. + */ readonly validation_regex: string | null; readonly validation_min: number | null; readonly validation_max: number | null; @@ -2615,6 +3519,9 @@ export interface PrometheusConfig { // From codersdk/deployment.go export interface ProvisionerConfig { + /** + * Daemons is the number of built-in terraform provisioners. + */ readonly daemons: number; readonly daemon_types: string; readonly daemon_poll_interval: number; @@ -2635,6 +3542,9 @@ export interface ProvisionerDaemon { readonly api_version: string; readonly provisioners: readonly ProvisionerType[]; readonly tags: Record; + /** + * Optional fields. + */ readonly key_name: string | null; readonly status: ProvisionerDaemonStatus | null; readonly current_job: ProvisionerDaemonJob | null; @@ -2651,9 +3561,15 @@ export interface ProvisionerDaemonJob { } // From codersdk/client.go +/** + * ProvisionerDaemonKey contains the authentication key for an external provisioner daemon + */ export const ProvisionerDaemonKey = "Coder-Provisioner-Daemon-Key"; // From codersdk/client.go +/** + * ProvisionerDaemonPSK contains the authentication pre-shared key for an external provisioner daemon + */ export const ProvisionerDaemonPSK = "Coder-Provisioner-Daemon-PSK"; // From codersdk/provisionerdaemons.go @@ -2666,6 +3582,9 @@ export const ProvisionerDaemonStatuses: ProvisionerDaemonStatus[] = [ ]; // From healthsdk/healthsdk.go +/** + * ProvisionerDaemonsReport includes health details of each connected provisioner daemon. + */ export interface ProvisionerDaemonsReport extends BaseReport { readonly items: readonly ProvisionerDaemonsReportItem[]; } @@ -2677,6 +3596,9 @@ export interface ProvisionerDaemonsReportItem { } // From codersdk/provisionerdaemons.go +/** + * ProvisionerJob describes the job executed by the provisioning daemon. + */ export interface ProvisionerJob { readonly id: string; readonly created_at: string; @@ -2702,6 +3624,9 @@ export interface ProvisionerJob { } // From codersdk/provisionerdaemons.go +/** + * ProvisionerJobInput represents the input for the job. + */ export interface ProvisionerJobInput { readonly template_version_id?: string; readonly workspace_build_id?: string; @@ -2709,6 +3634,9 @@ export interface ProvisionerJobInput { } // From codersdk/provisionerdaemons.go +/** + * ProvisionerJobLog represents the provisioner log entry annotated with source and level. + */ export interface ProvisionerJobLog { readonly id: number; readonly created_at: string; @@ -2719,6 +3647,9 @@ export interface ProvisionerJobLog { } // From codersdk/provisionerdaemons.go +/** + * ProvisionerJobMetadata contains metadata for the job. + */ export interface ProvisionerJobMetadata { readonly template_version_name: string; readonly template_id: string; @@ -2824,8 +3755,19 @@ export type ProvisionerType = "echo" | "terraform"; export const ProvisionerTypes: ProvisionerType[] = ["echo", "terraform"]; // From codersdk/workspaceproxy.go +/** + * ProxyHealthReport is a report of the health of the workspace proxy. + * A healthy report will have no errors. Warnings are not fatal. + */ export interface ProxyHealthReport { + /** + * Errors are problems that prevent the workspace proxy from being healthy + */ readonly errors: readonly string[]; + /** + * Warnings do not prevent the workspace proxy from being healthy, but + * should be addressed. + */ readonly warnings: readonly string[]; } @@ -2844,6 +3786,10 @@ export const ProxyHealthStatuses: ProxyHealthStatus[] = [ ]; // From codersdk/workspaces.go +/** + * PutExtendWorkspaceRequest is a request to extend the deadline of + * the active workspace build. + */ export interface PutExtendWorkspaceRequest { readonly deadline: string; } @@ -2990,6 +3936,12 @@ export interface RateLimitConfig { } // From codersdk/users.go +/** + * ReducedUser omits role and organization information. Roles are deduced from + * the user's site and organization roles. This requires fetching the user's + * organizational memberships. Fetching that is more expensive, and not usually + * required by the frontend. + */ export interface ReducedUser extends MinimalUser { readonly name?: string; readonly email: string; @@ -2998,6 +3950,10 @@ export interface ReducedUser extends MinimalUser { readonly last_seen_at?: string; readonly status: UserStatus; readonly login_type: LoginType; + /** + * Deprecated: this value should be retrieved from + * `codersdk.UserPreferenceSettings` instead. + */ readonly theme_preference?: string; } @@ -3008,7 +3964,18 @@ export interface Region { readonly display_name: string; readonly icon_url: string; readonly healthy: boolean; + /** + * PathAppURL is the URL to the base path for path apps. Optional + * unless wildcard_hostname is set. + * E.g. https://us.example.com + */ readonly path_app_url: string; + /** + * WildcardHostname is the wildcard hostname for subdomain apps. + * E.g. *.us.example.com + * E.g. *--suffix.au.example.com + * Optional. Does not need to be on the same domain as PathAppURL. + */ readonly wildcard_hostname: string; } @@ -3022,16 +3989,40 @@ export interface RegionsResponse { // From codersdk/replicas.go export interface Replica { + /** + * ID is the unique identifier for the replica. + */ readonly id: string; + /** + * Hostname is the hostname of the replica. + */ readonly hostname: string; + /** + * CreatedAt is the timestamp when the replica was first seen. + */ readonly created_at: string; + /** + * RelayAddress is the accessible address to relay DERP connections. + */ readonly relay_address: string; + /** + * RegionID is the region of the replica. + */ readonly region_id: number; + /** + * Error is the replica error. + */ readonly error: string; + /** + * DatabaseLatency is the latency in microseconds to the database. + */ readonly database_latency: number; } // From codersdk/users.go +/** + * RequestOneTimePasscodeRequest enables callers to request a one-time-passcode to change their password. + */ export interface RequestOneTimePasscodeRequest { readonly email: string; } @@ -3100,76 +4091,165 @@ export const ResourceTypes: ResourceType[] = [ ]; // From codersdk/client.go +/** + * Response represents a generic HTTP response. + */ export interface Response { + /** + * Message is an actionable message that depicts actions the request took. + * These messages should be fully formed sentences with proper punctuation. + * Examples: + * - "A user has been created." + * - "Failed to create a user." + */ readonly message: string; + /** + * Detail is a debug message that provides further insight into why the + * action failed. This information can be technical and a regular golang + * err.Error() text. + * - "database: too many open connections" + * - "stat: too many open files" + */ readonly detail?: string; + /** + * Validations are form field-specific friendly error messages. They will be + * shown on a form field in the UI. These can also be used to add additional + * context if there is a set of errors in the primary 'Message'. + */ readonly validations?: readonly ValidationError[]; } // From codersdk/roles.go +/** + * Role is a longer form of SlimRole that includes permissions details. + */ export interface Role { readonly name: string; readonly organization_id?: string; readonly display_name: string; readonly site_permissions: readonly Permission[]; + /** + * OrganizationPermissions are specific for the organization in the field 'OrganizationID' above. + */ readonly organization_permissions: readonly Permission[]; readonly user_permissions: readonly Permission[]; } // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleAuditor = "auditor"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleMember = "member"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationAdmin = "organization-admin"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationAuditor = "organization-auditor"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationMember = "organization-member"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationTemplateAdmin = "organization-template-admin"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationUserAdmin = "organization-user-admin"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOrganizationWorkspaceCreationBan = "organization-workspace-creation-ban"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleOwner = "owner"; // From codersdk/idpsync.go export interface RoleSyncSettings { + /** + * Field is the name of the claim field that specifies what organization roles + * a user should be given. If empty, no roles will be synced. + */ readonly field: string; + /** + * Mapping is a map from OIDC groups to Coder organization roles. + */ readonly mapping: Record; } // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleTemplateAdmin = "template-admin"; // From codersdk/rbacroles.go +/** + * Ideally this roles would be generated from the rbac/roles.go package. + */ export const RoleUserAdmin = "user-admin"; // From codersdk/deployment.go +/** + * SSHConfig is configuration the cli & vscode extension use for configuring + * ssh connections. + */ export interface SSHConfig { + /** + * DeploymentName is the config-ssh Hostname prefix + */ readonly DeploymentName: string; + /** + * SSHConfigOptions are additional options to add to the ssh config file. + * This will override defaults. + */ readonly SSHConfigOptions: string; } // From codersdk/deployment.go export interface SSHConfigResponse { + /** + * HostnamePrefix is the prefix we append to workspace names for SSH hostnames. + * Deprecated: use HostnameSuffix instead. + */ readonly hostname_prefix: string; + /** + * HostnameSuffix is the suffix to append to workspace names for SSH hostnames. + */ readonly hostname_suffix: string; readonly ssh_config_options: Record; } // From healthsdk/healthsdk.go +/** + * STUNReport contains information about a given node's STUN capabilities. + */ export interface STUNReport { readonly Enabled: boolean; readonly CanSTUN: boolean; @@ -3177,9 +4257,16 @@ export interface STUNReport { } // From serpent/serpent.go +/** + * Annotations is an arbitrary key-mapping used to extend the Option and Command types. + * Its methods won't panic if the map is nil. + */ export type SerpentAnnotations = Record; // From serpent/serpent.go +/** + * Group describes a hierarchy of groups that an option or command belongs to. + */ export interface SerpentGroup { readonly parent?: SerpentGroup; readonly name?: string; @@ -3188,26 +4275,71 @@ export interface SerpentGroup { } // From serpent/option.go +/** + * Option is a configuration option for a CLI application. + */ export interface SerpentOption { readonly name?: string; readonly description?: string; + /** + * Required means this value must be set by some means. It requires + * `ValueSource != ValueSourceNone` + * If `Default` is set, then `Required` is ignored. + */ readonly required?: boolean; + /** + * Flag is the long name of the flag used to configure this option. If unset, + * flag configuring is disabled. + */ readonly flag?: string; + /** + * FlagShorthand is the one-character shorthand for the flag. If unset, no + * shorthand is used. + */ readonly flag_shorthand?: string; + /** + * Env is the environment variable used to configure this option. If unset, + * environment configuring is disabled. + */ readonly env?: string; + /** + * YAML is the YAML key used to configure this option. If unset, YAML + * configuring is disabled. + */ readonly yaml?: string; + /** + * Default is parsed into Value if set. + */ readonly default?: string; + /** + * Value includes the types listed in values.go. + */ // interface type, falling back to unknown // this is likely an enum in an external package "github.com/spf13/pflag.Value" readonly value?: unknown; + /** + * Annotations enable extensions to serpent higher up in the stack. It's useful for + * help formatting and documentation generation. + */ readonly annotations?: SerpentAnnotations; + /** + * Group is a group hierarchy that helps organize this option in help, configs + * and other documentation. + */ readonly group?: SerpentGroup; + /** + * UseInstead is a list of options that should be used instead of this one. + * The field is used to generate a deprecation warning. + */ readonly use_instead?: readonly SerpentOption[]; readonly hidden?: boolean; readonly value_source?: SerpentValueSource; } // From serpent/option.go +/** + * OptionSet is a group of options that can be applied to a command. + */ export type SerpentOptionSet = readonly SerpentOption[]; // From serpent/values.go @@ -3217,8 +4349,26 @@ export type SerpentStruct = T; export type SerpentValueSource = string; // From derp/derp_client.go +/** + * ServerInfoMessage is sent by the server upon first connect. + */ export interface ServerInfoMessage { + /** + * TokenBucketBytesPerSecond is how many bytes per second the + * server says it will accept, including all framing bytes. + * + * Zero means unspecified. There might be a limit, but the + * client need not try to respect it. + */ readonly TokenBucketBytesPerSecond: number; + /** + * TokenBucketBytesBurst is how many bytes the server will + * allow to burst, temporarily violating + * TokenBucketBytesPerSecond. + * + * Zero means unspecified. There might be a limit, but the + * client need not try to respect it. + */ readonly TokenBucketBytesBurst: number; } @@ -3239,6 +4389,9 @@ export const ServerSentEventTypes: ServerSentEventType[] = [ ]; // From codersdk/deployment.go +/** + * Deprecated: ServiceBannerConfig has been renamed to BannerConfig. + */ export interface ServiceBannerConfig { readonly enabled: boolean; readonly message?: string; @@ -3254,9 +4407,39 @@ export interface SessionCountDeploymentStats { } // From codersdk/deployment.go +/** + * SessionLifetime refers to "sessions" authenticating into Coderd. Coder has + * multiple different session types: api keys, tokens, workspace app tokens, + * agent tokens, etc. This configuration struct should be used to group all + * settings referring to any of these session lifetime controls. + * TODO: These config options were created back when coder only had api keys. + * Today, the config is ambigously used for all of them. For example: + * - cli based api keys ignore all settings + * - login uses the default lifetime, not the MaximumTokenDuration + * - Tokens use the Default & MaximumTokenDuration + * - ... etc ... + * The rational behind each decision is undocumented. The naming behind these + * config options is also confusing without any clear documentation. + * 'CreateAPIKey' is used to make all sessions, and it's parameters are just + * 'LifetimeSeconds' and 'DefaultLifetime'. Which does not directly correlate to + * the config options here. + */ export interface SessionLifetime { + /** + * DisableExpiryRefresh will disable automatically refreshing api + * keys when they are used from the api. This means the api key lifetime at + * creation is the lifetime of the api key. + */ readonly disable_expiry_refresh?: boolean; + /** + * DefaultDuration is only for browser, workspace app and oauth sessions. + */ readonly default_duration: number; + /** + * RefreshDefaultDuration is the default lifetime for OAuth2 refresh tokens. + * This should generally be longer than access token lifetimes to allow + * refreshing after access token expiry. + */ readonly refresh_default_duration?: number; readonly default_token_lifetime?: number; readonly max_token_lifetime?: number; @@ -3264,15 +4447,39 @@ export interface SessionLifetime { } // From codersdk/client.go +/** + * SessionTokenHeader is the custom header to use for authentication. + */ export const SessionTokenHeader = "Coder-Session-Token"; // From codersdk/client.go +/** + * SignedAppTokenCookie is the name of the cookie that stores a temporary + * JWT that can be used to authenticate instead of the app session token. + *nolint:gosec + */ export const SignedAppTokenCookie = "coder_signed_app_token"; // From codersdk/client.go +/** + * SignedAppTokenQueryParameter is the name of the query parameter that + * stores a temporary JWT that can be used to authenticate instead of the + * session token. This is only acceptable on reconnecting-pty requests, not + * apps. + * + * It has a random suffix to avoid conflict with user query parameters on + * apps. + *nolint:gosec + */ export const SignedAppTokenQueryParameter = "coder_signed_app_token_23db1dde"; // From codersdk/roles.go +/** + * SlimRole omits permission information from a role. + * At present, this is because our apis do not return permission information, + * and it would require extra db calls to fetch this information. The UI does + * not need it, so most api calls will use this structure that omits information. + */ export interface SlimRole { readonly name: string; readonly display_name: string; @@ -3280,6 +4487,15 @@ export interface SlimRole { } // From codersdk/client.go +/** + * SubdomainAppSessionTokenCookie is the name of the cookie that stores an + * application-scoped API token on subdomain app domains (both the primary + * and proxies). + * + * To avoid conflicts between multiple proxies, we append an underscore and + * a hash suffix to the cookie name. + *nolint:gosec + */ export const SubdomainAppSessionTokenCookie = "coder_subdomain_app_session_token"; @@ -3310,33 +4526,165 @@ export interface TLSConfig { } // From tailcfg/derpmap.go +/** + * DERPNode describes a DERP packet relay node running within a DERPRegion. + */ export interface TailDERPNode { + /** + * Name is a unique node name (across all regions). + * It is not a host name. + * It's typically of the form "1b", "2a", "3b", etc. (region + * ID + suffix within that region) + */ readonly Name: string; + /** + * RegionID is the RegionID of the DERPRegion that this node + * is running in. + */ readonly RegionID: number; + /** + * HostName is the DERP node's hostname. + * + * It is required but need not be unique; multiple nodes may + * have the same HostName but vary in configuration otherwise. + */ readonly HostName: string; + /** + * CertName optionally specifies the expected TLS cert common + * name. If empty, HostName is used. If CertName is non-empty, + * HostName is only used for the TCP dial (if IPv4/IPv6 are + * not present) + TLS ClientHello. + */ readonly CertName?: string; + /** + * IPv4 optionally forces an IPv4 address to use, instead of using DNS. + * If empty, A record(s) from DNS lookups of HostName are used. + * If the string is not an IPv4 address, IPv4 is not used; the + * conventional string to disable IPv4 (and not use DNS) is + * "none". + */ readonly IPv4?: string; + /** + * IPv6 optionally forces an IPv6 address to use, instead of using DNS. + * If empty, AAAA record(s) from DNS lookups of HostName are used. + * If the string is not an IPv6 address, IPv6 is not used; the + * conventional string to disable IPv6 (and not use DNS) is + * "none". + */ readonly IPv6?: string; + /** + * Port optionally specifies a STUN port to use. + * Zero means 3478. + * To disable STUN on this node, use -1. + */ readonly STUNPort?: number; + /** + * STUNOnly marks a node as only a STUN server and not a DERP + * server. + */ readonly STUNOnly?: boolean; + /** + * DERPPort optionally provides an alternate TLS port number + * for the DERP HTTPS server. + * + * If zero, 443 is used. + */ readonly DERPPort?: number; + /** + * InsecureForTests is used by unit tests to disable TLS verification. + * It should not be set by users. + */ readonly InsecureForTests?: boolean; + /** + * ForceHTTP is used by unit tests to force HTTP. + * It should not be set by users. + */ readonly ForceHTTP?: boolean; + /** + * STUNTestIP is used in tests to override the STUN server's IP. + * If empty, it's assumed to be the same as the DERP server. + */ readonly STUNTestIP?: string; + /** + * CanPort80 specifies whether this DERP node is accessible over HTTP + * on port 80 specifically. This is used for captive portal checks. + */ readonly CanPort80?: boolean; } // From tailcfg/derpmap.go +/** + * DERPRegion is a geographic region running DERP relay node(s). + * + * Client nodes discover which region they're closest to, advertise + * that "home" DERP region (previously called "home node", when there + * was only 1 node per region) and maintain a persistent connection + * that region as long as it's the closest. Client nodes will further + * connect to other regions as necessary to communicate with peers + * advertising other regions as their homes. + */ export interface TailDERPRegion { + /** + * EmbeddedRelay is true when the region is bundled with the Coder + * control plane. + */ readonly EmbeddedRelay: boolean; + /** + * RegionID is a unique integer for a geographic region. + * + * It corresponds to the legacy derpN.tailscale.com hostnames + * used by older clients. (Older clients will continue to resolve + * derpN.tailscale.com when contacting peers, rather than use + * the server-provided DERPMap) + * + * RegionIDs must be non-zero, positive, and guaranteed to fit + * in a JavaScript number. + * + * RegionIDs in range 900-999 are reserved for end users to run their + * own DERP nodes. + */ readonly RegionID: number; + /** + * RegionCode is a short name for the region. It's usually a popular + * city or airport code in the region: "nyc", "sf", "sin", + * "fra", etc. + */ readonly RegionCode: string; + /** + * RegionName is a long English name for the region: "New York City", + * "San Francisco", "Singapore", "Frankfurt", etc. + */ readonly RegionName: string; + /** + * Avoid is whether the client should avoid picking this as its home + * region. The region should only be used if a peer is there. + * Clients already using this region as their home should migrate + * away to a new region without Avoid set. + */ readonly Avoid?: boolean; + /** + * Nodes are the DERP nodes running in this region, in + * priority order for the current client. Client TLS + * connections should ideally only go to the first entry + * (falling back to the second if necessary). STUN packets + * should go to the first 1 or 2. + * + * If nodes within a region route packets amongst themselves, + * but not to other regions. That said, each user/domain + * should get a the same preferred node order, so if all nodes + * for a user/network pick the first one (as they should, when + * things are healthy), the inter-cluster routing is minimal + * to zero. + */ readonly Nodes: readonly TailDERPNode[]; } // From codersdk/aitasks.go +/** + * Task represents a task. + * + * Experimental: This type is experimental and may change in the future. + */ export interface Task { readonly id: string; readonly organization_id: string; @@ -3361,6 +4709,11 @@ export interface Task { } // From codersdk/aitasks.go +/** + * TaskLogEntry represents a single log entry for a task. + * + * Experimental: This type is experimental and may change in the future. + */ export interface TaskLogEntry { readonly id: number; readonly content: string; @@ -3374,11 +4727,21 @@ export type TaskLogType = "input" | "output"; export const TaskLogTypes: TaskLogType[] = ["input", "output"]; // From codersdk/aitasks.go +/** + * TaskLogsResponse contains the logs for a task. + * + * Experimental: This type is experimental and may change in the future. + */ export interface TaskLogsResponse { readonly logs: readonly TaskLogEntry[]; } // From codersdk/aitasks.go +/** + * TaskSendRequest is used to send task input to the tasks sidebar app. + * + * Experimental: This type is experimental and may change in the future. + */ export interface TaskSendRequest { readonly input: string; } @@ -3387,6 +4750,11 @@ export interface TaskSendRequest { export type TaskState = "complete" | "failed" | "idle" | "working"; // From codersdk/aitasks.go +/** + * TaskStateEntry represents a single entry in the task's state history. + * + * Experimental: This type is experimental and may change in the future. + */ export interface TaskStateEntry { readonly timestamp: string; readonly state: TaskState; @@ -3402,7 +4770,15 @@ export const TaskStates: TaskState[] = [ ]; // From codersdk/aitasks.go +/** + * TasksFilter filters the list of tasks. + * + * Experimental: This type is experimental and may change in the future. + */ export interface TasksFilter { + /** + * Owner can be a username, UUID, or "me". + */ readonly owner?: string; } @@ -3414,6 +4790,10 @@ export interface TelemetryConfig { } // From codersdk/templates.go +/** + * Template is the JSON representation of a Coder template. This type matches the + * database object for now, but is abstracted for ease of change later on. + */ export interface Template { readonly id: string; readonly created_at: string; @@ -3426,6 +4806,9 @@ export interface Template { readonly display_name: string; readonly provisioner: ProvisionerType; readonly active_version_id: string; + /** + * ActiveUserCount is set to -1 when loading. + */ readonly active_user_count: number; readonly build_time_stats: TemplateBuildTimeStats; readonly description: string; @@ -3434,16 +4817,35 @@ export interface Template { readonly icon: string; readonly default_ttl_ms: number; readonly activity_bump_ms: number; + /** + * AutostopRequirement and AutostartRequirement are enterprise features. Its + * value is only used if your license is entitled to use the advanced template + * scheduling feature. + */ readonly autostop_requirement: TemplateAutostopRequirement; readonly autostart_requirement: TemplateAutostartRequirement; readonly created_by_id: string; readonly created_by_name: string; + /** + * AllowUserAutostart and AllowUserAutostop are enterprise-only. Their + * values are only used if your license is entitled to use the advanced + * template scheduling feature. + */ readonly allow_user_autostart: boolean; readonly allow_user_autostop: boolean; readonly allow_user_cancel_workspace_jobs: boolean; + /** + * FailureTTLMillis, TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their + * values are used if your license is entitled to use the advanced + * template scheduling feature. + */ readonly failure_ttl_ms: number; readonly time_til_dormant_ms: number; readonly time_til_dormant_autodelete_ms: number; + /** + * RequireActiveVersion mandates that workspaces are built with the active + * template version. + */ readonly require_active_version: boolean; readonly max_port_share_level: WorkspaceAgentPortShareLevel; readonly cors_behavior: CORSBehavior; @@ -3457,6 +4859,9 @@ export interface TemplateACL { } // From codersdk/insights.go +/** + * TemplateAppUsage shows the usage of an app for one or more templates. + */ export interface TemplateAppUsage { readonly template_ids: readonly string[]; readonly type: TemplateAppsType; @@ -3474,12 +4879,32 @@ export const TemplateAppsTypes: TemplateAppsType[] = ["app", "builtin"]; // From codersdk/templates.go export interface TemplateAutostartRequirement { + /** + * DaysOfWeek is a list of days of the week in which autostart is allowed + * to happen. If no days are specified, autostart is not allowed. + */ readonly days_of_week: readonly string[]; } // From codersdk/templates.go export interface TemplateAutostopRequirement { + /** + * DaysOfWeek is a list of days of the week on which restarts are required. + * Restarts happen within the user's quiet hours (in their configured + * timezone). If no days are specified, restarts are not required. Weekdays + * cannot be specified twice. + * + * Restarts will only happen on weekdays in this list on weeks which line up + * with Weeks. + */ readonly days_of_week: readonly string[]; + /** + * Weeks is the number of weeks between required restarts. Weeks are synced + * across all workspaces (and Coder deployments) using modulo math on a + * hardcoded epoch week of January 2nd, 2023 (the first Monday of 2023). + * Values of 0 or 1 indicate weekly restarts. Values of 2 indicate + * fortnightly restarts, etc. + */ readonly weeks: number; } @@ -3490,18 +4915,33 @@ export type TemplateBuildTimeStats = Record< >; // From codersdk/insights.go +/** + * Enums define the display name of the builtin app reported. + */ export const TemplateBuiltinAppDisplayNameJetBrains = "JetBrains"; // From codersdk/insights.go +/** + * Enums define the display name of the builtin app reported. + */ export const TemplateBuiltinAppDisplayNameSFTP = "SFTP"; // From codersdk/insights.go +/** + * Enums define the display name of the builtin app reported. + */ export const TemplateBuiltinAppDisplayNameSSH = "SSH"; // From codersdk/insights.go +/** + * Enums define the display name of the builtin app reported. + */ export const TemplateBuiltinAppDisplayNameVSCode = "Visual Studio Code"; // From codersdk/insights.go +/** + * Enums define the display name of the builtin app reported. + */ export const TemplateBuiltinAppDisplayNameWebTerminal = "Web Terminal"; // From codersdk/templates.go @@ -3526,6 +4966,10 @@ export interface TemplateGroup extends Group { } // From codersdk/insights.go +/** + * TemplateInsightsIntervalReport is the report from the template insights + * endpoint for a specific interval. + */ export interface TemplateInsightsIntervalReport { readonly start_time: string; readonly end_time: string; @@ -3535,6 +4979,9 @@ export interface TemplateInsightsIntervalReport { } // From codersdk/insights.go +/** + * TemplateInsightsReport is the report from the template insights endpoint. + */ export interface TemplateInsightsReport { readonly start_time: string; readonly end_time: string; @@ -3554,6 +5001,9 @@ export interface TemplateInsightsRequest { } // From codersdk/insights.go +/** + * TemplateInsightsResponse is the response from the template insights endpoint. + */ export interface TemplateInsightsResponse { readonly report?: TemplateInsightsReport; readonly interval_reports?: readonly TemplateInsightsIntervalReport[]; @@ -3568,6 +5018,10 @@ export const TemplateInsightsSections: TemplateInsightsSection[] = [ ]; // From codersdk/insights.go +/** + * TemplateParameterUsage shows the usage of a parameter for one or more + * templates. + */ export interface TemplateParameterUsage { readonly template_ids: readonly string[]; readonly display_name: string; @@ -3579,6 +5033,10 @@ export interface TemplateParameterUsage { } // From codersdk/insights.go +/** + * TemplateParameterValue shows the usage of a parameter value for one or more + * templates. + */ export interface TemplateParameterValue { readonly value: string; readonly count: number; @@ -3595,6 +5053,9 @@ export interface TemplateUser extends User { } // From codersdk/templateversions.go +/** + * TemplateVersion represents a single version of a template. + */ export interface TemplateVersion { readonly id: string; readonly template_id?: string; @@ -3624,12 +5085,19 @@ export interface TemplateVersionExternalAuth { } // From codersdk/templateversions.go +/** + * TemplateVersionParameter represents a parameter for a template version. + */ export interface TemplateVersionParameter { readonly name: string; readonly display_name?: string; readonly description: string; readonly description_plaintext: string; readonly type: string; + /** + * FormType has an enum value of empty string, `""`. + * Keep the leading comma in the enums struct tag. + */ readonly form_type: string; readonly mutable: boolean; readonly default_value: string; @@ -3645,6 +5113,9 @@ export interface TemplateVersionParameter { } // From codersdk/templateversions.go +/** + * TemplateVersionParameterOption represents a selectable option for a template parameter. + */ export interface TemplateVersionParameterOption { readonly name: string; readonly description: string; @@ -3653,6 +5124,9 @@ export interface TemplateVersionParameterOption { } // From codersdk/templateversions.go +/** + * TemplateVersionVariable represents a managed template variable. + */ export interface TemplateVersionVariable { readonly name: string; readonly description: string; @@ -3671,6 +5145,10 @@ export const TemplateVersionWarnings: TemplateVersionWarning[] = [ ]; // From codersdk/templates.go +/** + * TemplateVersionsByTemplateRequest defines the request parameters for + * TemplateVersionsByTemplate. + */ export interface TemplateVersionsByTemplateRequest extends Pagination { readonly template_id: string; readonly include_archived: boolean; @@ -3747,14 +5225,29 @@ export interface UpdateActiveTemplateVersion { export interface UpdateAppearanceConfig { readonly application_name: string; readonly logo_url: string; + /** + * Deprecated: ServiceBanner has been replaced by AnnouncementBanners. + */ readonly service_banner: BannerConfig; readonly announcement_banners: readonly BannerConfig[]; } // From codersdk/updatecheck.go +/** + * UpdateCheckResponse contains information on the latest release of Coder. + */ export interface UpdateCheckResponse { + /** + * Current indicates whether the server version is the same as the latest. + */ readonly current: boolean; + /** + * Version is the semantic version for the latest release of Coder. + */ readonly version: string; + /** + * URL to download the latest release of Coder. + */ readonly url: string; } @@ -3794,7 +5287,17 @@ export interface UpdateRoles { // From codersdk/templates.go export interface UpdateTemplateACL { + /** + * UserPerms is a mapping from valid user UUIDs to the template role they + * should be granted. To remove a user from the template, use "" as the role + * (available as a constant named codersdk.TemplateRoleDeleted) + */ readonly user_perms?: Record; + /** + * GroupPerms is a mapping from valid group UUIDs to the template role they + * should be granted. To remove a group from the template, use "" as the role + * (available as a constant named codersdk.TemplateRoleDeleted) + */ readonly group_perms?: Record; } @@ -3805,7 +5308,17 @@ export interface UpdateTemplateMeta { readonly description?: string; readonly icon?: string; readonly default_ttl_ms?: number; + /** + * ActivityBumpMillis allows optionally specifying the activity bump + * duration for all workspaces created from this template. Defaults to 1h + * but can be set to 0 to disable activity bumping. + */ readonly activity_bump_ms?: number; + /** + * AutostopRequirement and AutostartRequirement can only be set if your license + * includes the advanced template scheduling feature. If you attempt to set this + * value while unlicensed, it will be ignored. + */ readonly autostop_requirement?: TemplateAutostopRequirement; readonly autostart_requirement?: TemplateAutostartRequirement; readonly allow_user_autostart?: boolean; @@ -3814,13 +5327,49 @@ export interface UpdateTemplateMeta { readonly failure_ttl_ms?: number; readonly time_til_dormant_ms?: number; readonly time_til_dormant_autodelete_ms?: number; + /** + * UpdateWorkspaceLastUsedAt updates the last_used_at field of workspaces + * spawned from the template. This is useful for preventing workspaces being + * immediately locked when updating the inactivity_ttl field to a new, shorter + * value. + */ readonly update_workspace_last_used_at: boolean; + /** + * UpdateWorkspaceDormant updates the dormant_at field of workspaces spawned + * from the template. This is useful for preventing dormant workspaces being immediately + * deleted when updating the dormant_ttl field to a new, shorter value. + */ readonly update_workspace_dormant_at: boolean; + /** + * RequireActiveVersion mandates workspaces built using this template + * use the active version of the template. This option has no + * effect on template admins. + */ readonly require_active_version?: boolean; + /** + * DeprecationMessage if set, will mark the template as deprecated and block + * any new workspaces from using this template. + * If passed an empty string, will remove the deprecated message, making + * the template usable for new workspaces again. + */ readonly deprecation_message?: string; + /** + * DisableEveryoneGroupAccess allows optionally disabling the default + * behavior of granting the 'everyone' group access to use the template. + * If this is set to true, the template will not be available to all users, + * and must be explicitly granted to users or groups in the permissions settings + * of the template. + */ readonly disable_everyone_group_access: boolean; readonly max_port_share_level?: WorkspaceAgentPortShareLevel; readonly cors_behavior?: CORSBehavior; + /** + * UseClassicParameterFlow is a flag that switches the default behavior to use the classic + * parameter flow when creating a workspace. This only affects deployments with the experiment + * "dynamic-parameters" enabled. This setting will live for a period after the experiment is + * made the default. + * An "opt-out" is present in case the new feature breaks some existing templates. + */ readonly use_classic_parameter_flow?: boolean; } @@ -3849,26 +5398,64 @@ export interface UpdateUserProfileRequest { // From codersdk/users.go export interface UpdateUserQuietHoursScheduleRequest { + /** + * Schedule is a cron expression that defines when the user's quiet hours + * window is. Schedule must not be empty. For new users, the schedule is set + * to 2am in their browser or computer's timezone. The schedule denotes the + * beginning of a 4 hour window where the workspace is allowed to + * automatically stop or restart due to maintenance or template schedule. + * + * The schedule must be daily with a single time, and should have a timezone + * specified via a CRON_TZ prefix (otherwise UTC will be used). + * + * If the schedule is empty, the user will be updated to use the default + * schedule. + */ readonly schedule: string; } // From codersdk/workspaces.go export interface UpdateWorkspaceACL { + /** + * UserRoles is a mapping from valid user UUIDs to the workspace role they + * should be granted. To remove a user from the workspace, use "" as the role + * (available as a constant named codersdk.WorkspaceRoleDeleted) + */ readonly user_roles?: Record; + /** + * GroupRoles is a mapping from valid group UUIDs to the workspace role they + * should be granted. To remove a group from the workspace, use "" as the role + * (available as a constant named codersdk.WorkspaceRoleDeleted) + */ readonly group_roles?: Record; } // From codersdk/workspaces.go +/** + * UpdateWorkspaceAutomaticUpdatesRequest is a request to updates a workspace's automatic updates setting. + */ export interface UpdateWorkspaceAutomaticUpdatesRequest { readonly automatic_updates: AutomaticUpdates; } // From codersdk/workspaces.go +/** + * UpdateWorkspaceAutostartRequest is a request to update a workspace's autostart schedule. + */ export interface UpdateWorkspaceAutostartRequest { + /** + * Schedule is expected to be of the form `CRON_TZ= * * ` + * Example: `CRON_TZ=US/Central 30 9 * * 1-5` represents 0930 in the timezone US/Central + * on weekdays (Mon-Fri). `CRON_TZ` defaults to UTC if not present. + */ readonly schedule?: string; } // From codersdk/workspaces.go +/** + * UpdateWorkspaceDormancy is a request to activate or make a workspace dormant. + * A value of false will activate a dormant workspace. + */ export interface UpdateWorkspaceDormancy { readonly dormant: boolean; } @@ -3885,11 +5472,17 @@ export interface UpdateWorkspaceRequest { } // From codersdk/workspaces.go +/** + * UpdateWorkspaceTTLRequest is a request to update a workspace's TTL. + */ export interface UpdateWorkspaceTTLRequest { readonly ttl_ms: number | null; } // From codersdk/files.go +/** + * UploadResponse contains the hash to reference the uploaded file. + */ export interface UploadResponse { readonly hash: string; } @@ -3920,12 +5513,18 @@ export interface UsagePeriod { } // From codersdk/users.go +/** + * User represents a user in Coder. + */ export interface User extends ReducedUser { readonly organization_ids: readonly string[]; readonly roles: readonly SlimRole[]; } // From codersdk/insights.go +/** + * UserActivity shows the session time for a user. + */ export interface UserActivity { readonly template_ids: readonly string[]; readonly user_id: string; @@ -3935,6 +5534,10 @@ export interface UserActivity { } // From codersdk/insights.go +/** + * UserActivityInsightsReport is the report from the user activity insights + * endpoint. + */ export interface UserActivityInsightsReport { readonly start_time: string; readonly end_time: string; @@ -3950,6 +5553,10 @@ export interface UserActivityInsightsRequest { } // From codersdk/insights.go +/** + * UserActivityInsightsResponse is the response from the user activity insights + * endpoint. + */ export interface UserActivityInsightsResponse { readonly report: UserActivityInsightsReport; } @@ -3961,6 +5568,9 @@ export interface UserAppearanceSettings { } // From codersdk/insights.go +/** + * UserLatency shows the connection latency for a user. + */ export interface UserLatency { readonly template_ids: readonly string[]; readonly user_id: string; @@ -3970,6 +5580,10 @@ export interface UserLatency { } // From codersdk/insights.go +/** + * UserLatencyInsightsReport is the report from the user latency insights + * endpoint. + */ export interface UserLatencyInsightsReport { readonly start_time: string; readonly end_time: string; @@ -3985,6 +5599,10 @@ export interface UserLatencyInsightsRequest { } // From codersdk/insights.go +/** + * UserLatencyInsightsResponse is the response from the user latency insights + * endpoint. + */ export interface UserLatencyInsightsResponse { readonly report: UserLatencyInsightsReport; } @@ -4009,10 +5627,26 @@ export interface UserQuietHoursScheduleConfig { // From codersdk/users.go export interface UserQuietHoursScheduleResponse { readonly raw_schedule: string; + /** + * UserSet is true if the user has set their own quiet hours schedule. If + * false, the user is using the default schedule. + */ readonly user_set: boolean; + /** + * UserCanSet is true if the user is allowed to set their own quiet hours + * schedule. If false, the user cannot set a custom schedule and the default + * schedule will always be used. + */ readonly user_can_set: boolean; - readonly time: string; - readonly timezone: string; + /** + * Time is the time of day that the quiet hours window starts in the given + * Timezone each day. + */ + readonly time: string; // HH:mm (24-hour) + readonly timezone: string; // raw format from the cron expression, UTC if unspecified + /** + * Next is the next time that the quiet hours window will start. + */ readonly next: string; } @@ -4050,6 +5684,9 @@ export interface ValidateUserPasswordResponse { } // From codersdk/client.go +/** + * ValidationError represents a scoped error to a user input. + */ export interface ValidationError { readonly field: string; readonly detail: string; @@ -4091,18 +5728,31 @@ export interface WebpushSubscription { } // From healthsdk/healthsdk.go +/** + * WebsocketReport shows if the configured access URL allows establishing WebSocket connections. + */ export interface WebsocketReport extends BaseReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly body: string; readonly code: number; } // From codersdk/workspaces.go +/** + * Workspace is a deployment of a template. It references a specific + * version and can be updated. + */ export interface Workspace { readonly id: string; readonly created_at: string; readonly updated_at: string; readonly owner_id: string; + /** + * OwnerName is the username of the owner of the workspace. + */ readonly owner_name: string; readonly owner_avatar_url: string; readonly organization_id: string; @@ -4122,13 +5772,35 @@ export interface Workspace { readonly autostart_schedule?: string; readonly ttl_ms?: number; readonly last_used_at: string; + /** + * DeletingAt indicates the time at which the workspace will be permanently deleted. + * A workspace is eligible for deletion if it is dormant (a non-nil dormant_at value) + * and a value has been specified for time_til_dormant_autodelete on its template. + */ readonly deleting_at: string | null; + /** + * DormantAt being non-nil indicates a workspace that is dormant. + * A dormant workspace is no longer accessible must be activated. + * It is subject to deletion if it breaches + * the duration of the time_til_ field on its template. + */ readonly dormant_at: string | null; + /** + * Health shows the health of the workspace and information about + * what is causing an unhealthy status. + */ readonly health: WorkspaceHealth; readonly automatic_updates: AutomaticUpdates; readonly allow_renames: boolean; readonly favorite: boolean; readonly next_start_at: string | null; + /** + * IsPrebuild indicates whether the workspace is a prebuilt workspace. + * Prebuilt workspaces are owned by the prebuilds system user and have specific behavior, + * such as being managed differently from regular workspaces. + * Once a prebuilt workspace is claimed by a user, it transitions to a regular workspace, + * and IsPrebuild returns false. + */ readonly is_prebuild: boolean; } @@ -4164,44 +5836,111 @@ export interface WorkspaceAgent { readonly version: string; readonly api_version: string; readonly apps: readonly WorkspaceApp[]; + /** + * DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). + */ readonly latency?: Record; readonly connection_timeout_seconds: number; readonly troubleshooting_url: string; readonly subsystems: readonly AgentSubsystem[]; - readonly health: WorkspaceAgentHealth; + readonly health: WorkspaceAgentHealth; // Health reports the health of the agent. readonly display_apps: readonly DisplayApp[]; readonly log_sources: readonly WorkspaceAgentLogSource[]; readonly scripts: readonly WorkspaceAgentScript[]; + /** + * StartupScriptBehavior is a legacy field that is deprecated in favor + * of the `coder_script` resource. It's only referenced by old clients. + * Deprecated: Remove in the future! + */ readonly startup_script_behavior: WorkspaceAgentStartupScriptBehavior; } // From codersdk/workspaceagents.go +/** + * WorkspaceAgentContainer describes a devcontainer of some sort + * that is visible to the workspace agent. This struct is an abstraction + * of potentially multiple implementations, and the fields will be + * somewhat implementation-dependent. + */ export interface WorkspaceAgentContainer { + /** + * CreatedAt is the time the container was created. + */ readonly created_at: string; + /** + * ID is the unique identifier of the container. + */ readonly id: string; + /** + * FriendlyName is the human-readable name of the container. + */ readonly name: string; + /** + * Image is the name of the container image. + */ readonly image: string; + /** + * Labels is a map of key-value pairs of container labels. + */ readonly labels: Record; + /** + * Running is true if the container is currently running. + */ readonly running: boolean; + /** + * Ports includes ports exposed by the container. + */ readonly ports: readonly WorkspaceAgentContainerPort[]; + /** + * Status is the current status of the container. This is somewhat + * implementation-dependent, but should generally be a human-readable + * string. + */ readonly status: string; + /** + * Volumes is a map of "things" mounted into the container. Again, this + * is somewhat implementation-dependent. + */ readonly volumes: Record; } // From codersdk/workspaceagents.go +/** + * WorkspaceAgentContainerPort describes a port as exposed by a container. + */ export interface WorkspaceAgentContainerPort { + /** + * Port is the port number *inside* the container. + */ readonly port: number; + /** + * Network is the network protocol used by the port (tcp, udp, etc). + */ readonly network: string; + /** + * HostIP is the IP address of the host interface to which the port is + * bound. Note that this can be an IPv4 or IPv6 address. + */ readonly host_ip?: string; + /** + * HostPort is the port number *outside* the container. + */ readonly host_port?: number; } // From codersdk/workspaceagents.go +/** + * WorkspaceAgentDevcontainer defines the location of a devcontainer + * configuration in a workspace that is visible to the workspace agent. + */ export interface WorkspaceAgentDevcontainer { readonly id: string; readonly name: string; readonly workspace_folder: string; readonly config_path?: string; + /** + * Additional runtime fields. + */ readonly status: WorkspaceAgentDevcontainerStatus; readonly dirty: boolean; readonly container?: WorkspaceAgentContainer; @@ -4210,6 +5949,10 @@ export interface WorkspaceAgentDevcontainer { } // From codersdk/workspaceagents.go +/** + * WorkspaceAgentDevcontainerAgent represents the sub agent for a + * devcontainer. + */ export interface WorkspaceAgentDevcontainerAgent { readonly id: string; readonly name: string; @@ -4228,8 +5971,8 @@ export const WorkspaceAgentDevcontainerStatuses: WorkspaceAgentDevcontainerStatu // From codersdk/workspaceagents.go export interface WorkspaceAgentHealth { - readonly healthy: boolean; - readonly reason?: string; + readonly healthy: boolean; // Healthy is true if the agent is healthy. + readonly reason?: string; // Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true. } // From codersdk/workspaceagents.go @@ -4257,21 +6000,41 @@ export const WorkspaceAgentLifecycles: WorkspaceAgentLifecycle[] = [ ]; // From codersdk/workspaceagents.go +/** + * WorkspaceAgentListContainersResponse is the response to the list containers + * request. + */ export interface WorkspaceAgentListContainersResponse { + /** + * Devcontainers is a list of devcontainers visible to the workspace agent. + */ readonly devcontainers: readonly WorkspaceAgentDevcontainer[]; + /** + * Containers is a list of containers visible to the workspace agent. + */ readonly containers: readonly WorkspaceAgentContainer[]; + /** + * Warnings is a list of warnings that may have occurred during the + * process of listing containers. This should not include fatal errors. + */ readonly warnings?: readonly string[]; } // From codersdk/workspaceagents.go export interface WorkspaceAgentListeningPort { - readonly process_name: string; - readonly network: string; + readonly process_name: string; // may be empty + readonly network: string; // only "tcp" at the moment readonly port: number; } // From codersdk/workspaceagents.go export interface WorkspaceAgentListeningPortsResponse { + /** + * If there are no ports in the list, nothing should be displayed in the UI. + * There must not be a "no ports available" message or anything similar, as + * there will always be no ports displayed on platforms where our port + * detection logic is unsupported. + */ readonly ports: readonly WorkspaceAgentListeningPort[]; } @@ -4300,6 +6063,11 @@ export interface WorkspaceAgentMetadata { } // From codersdk/workspaceagents.go +/** + * WorkspaceAgentMetadataDescription is a description of dynamic metadata the agent should report + * back to coderd. It is provided via the `metadata` list in the `coder_agent` + * block. + */ export interface WorkspaceAgentMetadataDescription { readonly display_name: string; readonly key: string; @@ -4311,6 +6079,10 @@ export interface WorkspaceAgentMetadataDescription { // From codersdk/workspaceagents.go export interface WorkspaceAgentMetadataResult { readonly collected_at: string; + /** + * Age is the number of seconds since the metadata was collected. + * It is provided in addition to CollectedAt to protect against clock skew. + */ readonly age: number; readonly value: string; readonly error: string; @@ -4387,21 +6159,58 @@ export const WorkspaceAgentStatuses: WorkspaceAgentStatus[] = [ // From codersdk/workspaceapps.go export interface WorkspaceApp { readonly id: string; + /** + * URL is the address being proxied to inside the workspace. + * If external is specified, this will be opened on the client. + */ readonly url?: string; + /** + * External specifies whether the URL should be opened externally on + * the client or not. + */ readonly external: boolean; + /** + * Slug is a unique identifier within the agent. + */ readonly slug: string; + /** + * DisplayName is a friendly name for the app. + */ readonly display_name?: string; readonly command?: string; + /** + * Icon is a relative path or external URL that specifies + * an icon to be displayed in the dashboard. + */ readonly icon?: string; + /** + * Subdomain denotes whether the app should be accessed via a path on the + * `coder server` or via a hostname-based dev URL. If this is set to true + * and there is no app wildcard configured on the server, the app will not + * be accessible in the UI. + */ readonly subdomain: boolean; + /** + * SubdomainName is the application domain exposed on the `coder server`. + */ readonly subdomain_name?: string; readonly sharing_level: WorkspaceAppSharingLevel; + /** + * Healthcheck specifies the configuration for checking app health. + */ readonly healthcheck?: Healthcheck; readonly health: WorkspaceAppHealth; readonly group?: string; readonly hidden: boolean; readonly open_in: WorkspaceAppOpenIn; + /** + * Tooltip is an optional markdown supported field that is displayed + * when hovering over workspace apps in the UI. + */ readonly tooltip?: string; + /** + * Statuses is a list of statuses for the app. + */ readonly statuses: readonly WorkspaceAppStatus[]; } @@ -4447,8 +6256,21 @@ export interface WorkspaceAppStatus { readonly app_id: string; readonly state: WorkspaceAppStatusState; readonly message: string; + /** + * URI is the URI of the resource that the status is for. + * e.g. https://github.com/org/repo/pull/123 + * e.g. file:///path/to/file + */ readonly uri: string; + /** + * Deprecated: This field is unused and will be removed in a future version. + * Icon is an external URL to an icon that will be rendered in the UI. + */ readonly icon: string; + /** + * Deprecated: This field is unused and will be removed in a future version. + * NeedsUserAttention specifies whether the status needs user attention. + */ readonly needs_user_attention: boolean; } @@ -4467,6 +6289,10 @@ export const WorkspaceAppStatusStates: WorkspaceAppStatusState[] = [ ]; // From codersdk/workspacebuilds.go +/** + * WorkspaceBuild is an at-point representation of a workspace state. + * BuildNumbers start at 1 and increase by 1 for each subsequent build + */ export interface WorkspaceBuild { readonly id: string; readonly created_at: string; @@ -4474,6 +6300,9 @@ export interface WorkspaceBuild { readonly workspace_id: string; readonly workspace_name: string; readonly workspace_owner_id: string; + /** + * WorkspaceOwnerName is the username of the owner of the workspace. + */ readonly workspace_owner_name: string; readonly workspace_owner_avatar_url?: string; readonly template_version_id: string; @@ -4497,6 +6326,9 @@ export interface WorkspaceBuild { } // From codersdk/workspacebuilds.go +/** + * WorkspaceBuildParameter represents a parameter specific for a workspace build. + */ export interface WorkspaceBuildParameter { readonly name: string; readonly value: string; @@ -4505,6 +6337,10 @@ export interface WorkspaceBuildParameter { // From codersdk/workspacebuilds.go export interface WorkspaceBuildTimings { readonly provisioner_timings: readonly ProvisionerTiming[]; + /** + * TODO: Consolidate agent-related timing metrics into a single struct when + * updating the API version + */ readonly agent_script_timings: readonly AgentScriptTiming[]; readonly agent_connection_timings: readonly AgentConnectionTiming[]; } @@ -4534,6 +6370,9 @@ export interface WorkspaceDeploymentStats { // From codersdk/workspaces.go export interface WorkspaceFilter { + /** + * FilterQuery supports a raw filter query string + */ readonly q?: string; } @@ -4544,8 +6383,8 @@ export interface WorkspaceGroup extends Group { // From codersdk/workspaces.go export interface WorkspaceHealth { - readonly healthy: boolean; - readonly failing_agents: readonly string[]; + readonly healthy: boolean; // Healthy is true if the workspace is healthy. + readonly failing_agents: readonly string[]; // FailingAgents lists the IDs of the agents that are failing, if any. } // From codersdk/workspaces.go @@ -4557,6 +6396,11 @@ export interface WorkspaceOptions { export interface WorkspaceProxy extends Region { readonly derp_enabled: boolean; readonly derp_only: boolean; + /** + * Status is the latest status check of the proxy. This will be empty for deleted + * proxies. This value can be used to determine if a workspace proxy is healthy + * and ready to use. + */ readonly status?: WorkspaceProxyStatus; readonly created_at: string; readonly updated_at: string; @@ -4566,12 +6410,24 @@ export interface WorkspaceProxy extends Region { // From codersdk/deployment.go export interface WorkspaceProxyBuildInfo { + /** + * TODO: @emyrk what should we include here? + */ readonly workspace_proxy: boolean; + /** + * DashboardURL is the URL of the coderd this proxy is connected to. + */ readonly dashboard_url: string; } // From healthsdk/healthsdk.go +/** + * WorkspaceProxyReport includes health details of each connected workspace proxy. + */ export interface WorkspaceProxyReport extends BaseReport { + /** + * Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead. + */ readonly healthy: boolean; readonly workspace_proxies: RegionsResponse; } @@ -4579,6 +6435,9 @@ export interface WorkspaceProxyReport extends BaseReport { // From codersdk/workspaceproxy.go export interface WorkspaceProxyStatus { readonly status: ProxyHealthStatus; + /** + * Report provides more information about the health of the workspace proxy. + */ readonly report?: ProxyHealthReport; readonly checked_at: string; } @@ -4590,6 +6449,10 @@ export interface WorkspaceQuota { } // From codersdk/workspacebuilds.go +/** + * WorkspaceResource describes resources used to create a workspace, for instance: + * containers, images, volumes. + */ export interface WorkspaceResource { readonly id: string; readonly created_at: string; @@ -4605,6 +6468,9 @@ export interface WorkspaceResource { } // From codersdk/workspacebuilds.go +/** + * WorkspaceResourceMetadata annotates the workspace resource with custom key-value pairs. + */ export interface WorkspaceResourceMetadata { readonly key: string; readonly value: string;