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;