From ab04627e976f14044ade5ccc339e1311ff8e2389 Mon Sep 17 00:00:00 2001 From: Chris Olszewski Date: Wed, 28 Aug 2024 10:04:30 -0400 Subject: [PATCH] chore(config): add undocummented `remote` types to `turbo.json` schema (#9073) ### Description There has been an undocumented `remoteCache` field in `turbo.json` for quite awhile (at least since 1.10). This PR adds documentation for the it. ### Testing Instructions Added unit tests to verify that when these are set in `turbo.json` they are respected in the built config. --- crates/turborepo-lib/src/config.rs | 46 ++++++++++++++++++ docs/repo-docs/reference/configuration.mdx | 53 +++++++++++++++++++++ packages/turbo-types/schemas/schema.json | 16 +++++++ packages/turbo-types/schemas/schema.v2.json | 16 +++++++ packages/turbo-types/src/types/config-v2.ts | 32 +++++++++++++ 5 files changed, 163 insertions(+) diff --git a/crates/turborepo-lib/src/config.rs b/crates/turborepo-lib/src/config.rs index 0ae98f032886e..9b7d74298617d 100644 --- a/crates/turborepo-lib/src/config.rs +++ b/crates/turborepo-lib/src/config.rs @@ -1050,4 +1050,50 @@ mod test { assert_eq!(config.token().unwrap(), vercel_artifacts_token); assert_eq!(config.spaces_id().unwrap(), "my-spaces-id"); } + + #[test] + fn test_turbo_json_remote_cache() { + let tmp_dir = TempDir::new().unwrap(); + let repo_root = AbsoluteSystemPathBuf::try_from(tmp_dir.path()).unwrap(); + + let api_url = "url1"; + let login_url = "url2"; + let team_slug = "my-slug"; + let team_id = "an-id"; + let turbo_json_contents = serde_json::to_string_pretty(&serde_json::json!({ + "remoteCache": { + "enabled": true, + "apiUrl": api_url, + "loginUrl": login_url, + "teamSlug": team_slug, + "teamId": team_id, + "signature": true, + "preflight": false, + "timeout": 123 + } + })) + .unwrap(); + repo_root + .join_component("turbo.json") + .create_with_contents(&turbo_json_contents) + .unwrap(); + + let builder = TurborepoConfigBuilder { + repo_root, + override_config: ConfigurationOptions::default(), + global_config_path: None, + environment: HashMap::default(), + }; + + let config = builder.build().unwrap(); + // Directly accessing field to make sure we're not getting the default value + assert_eq!(config.enabled, Some(true)); + assert_eq!(config.api_url(), api_url); + assert_eq!(config.login_url(), login_url); + assert_eq!(config.team_slug(), Some(team_slug)); + assert_eq!(config.team_id(), Some(team_id)); + assert!(config.signature()); + assert!(!config.preflight()); + assert_eq!(config.timeout(), 123); + } } diff --git a/docs/repo-docs/reference/configuration.mdx b/docs/repo-docs/reference/configuration.mdx index 8e794a015e3e5..9e503ee11b4e7 100644 --- a/docs/repo-docs/reference/configuration.mdx +++ b/docs/repo-docs/reference/configuration.mdx @@ -476,3 +476,56 @@ This task is most useful for scripts that can be manipulated while they are runn } } ``` + +## Remote caching + +The global `remoteCache` option has a variety of fields for configuring remote cache usage + +```jsonc title="./turbo.json" +{ + "remoteCache": {} +} +``` + +### `enabled` + +Default: `true` + +Enables remote caching. + +When `false`, Turborepo will disable all remote cache operations, even if the repo has a valid token. +If true, remote caching is enabled, but still requires the user to login and link their repo to a remote cache. + +### `signature` + +Default: `false` + +Enables signature verification for requests to the remote cache. +When `true`, Turborepo will sign every uploaded artifact using the value of the environment variable `TURBO_REMOTE_CACHE_SIGNATURE_KEY`. +Turborepo will reject any downloaded artifacts that have an invalid signature or are missing a signature. + +### `preflight` + +Default: `false` + +When enabled, any HTTP request will be preceded by an OPTIONS request to determine if the request is supported by the endpoint. + +### `timeout` + +Default: `30` + +Sets a timeout for remote cache operations. +Value is given in seconds and only whole values are accepted. +If `0` is passed, then there is no timeout for any cache operations. + +### `apiUrl` + +Default: `"https://vercel.com"` + +Set endpoint for API calls to the remote cache. + +### `loginUrl` + +Default: `"https://vercel.com"` + +Set endpoint for requesting tokens during `turbo login`. diff --git a/packages/turbo-types/schemas/schema.json b/packages/turbo-types/schemas/schema.json index 134534a05af30..1ecea772ae15b 100644 --- a/packages/turbo-types/schemas/schema.json +++ b/packages/turbo-types/schemas/schema.json @@ -171,6 +171,22 @@ "enabled": { "type": "boolean", "description": "Indicates if the remote cache is enabled. When `false`, Turborepo will disable all remote cache operations, even if the repo has a valid token. If true, remote caching is enabled, but still requires the user to login and link their repo to a remote cache. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching" + }, + "preflight": { + "type": "boolean", + "description": "When enabled, any HTTP request will be preceded by an OPTIONS request to determine if the request is supported by the endpoint.\n\nDocumentation: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests" + }, + "apiUrl": { + "type": "string", + "description": "Set endpoint for API calls to the remote cache. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting" + }, + "loginUrl": { + "type": "string", + "description": "Set endpoint for requesting tokens during `turbo login`. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting" + }, + "timeout": { + "type": "number", + "description": "Sets a timeout for remote cache operations. Value is given in seconds and only whole values are accepted. If `0` is passed, then there is no timeout for any cache operations." } }, "additionalProperties": false diff --git a/packages/turbo-types/schemas/schema.v2.json b/packages/turbo-types/schemas/schema.v2.json index 134534a05af30..1ecea772ae15b 100644 --- a/packages/turbo-types/schemas/schema.v2.json +++ b/packages/turbo-types/schemas/schema.v2.json @@ -171,6 +171,22 @@ "enabled": { "type": "boolean", "description": "Indicates if the remote cache is enabled. When `false`, Turborepo will disable all remote cache operations, even if the repo has a valid token. If true, remote caching is enabled, but still requires the user to login and link their repo to a remote cache. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching" + }, + "preflight": { + "type": "boolean", + "description": "When enabled, any HTTP request will be preceded by an OPTIONS request to determine if the request is supported by the endpoint.\n\nDocumentation: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests" + }, + "apiUrl": { + "type": "string", + "description": "Set endpoint for API calls to the remote cache. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting" + }, + "loginUrl": { + "type": "string", + "description": "Set endpoint for requesting tokens during `turbo login`. Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting" + }, + "timeout": { + "type": "number", + "description": "Sets a timeout for remote cache operations. Value is given in seconds and only whole values are accepted. If `0` is passed, then there is no timeout for any cache operations." } }, "additionalProperties": false diff --git a/packages/turbo-types/src/types/config-v2.ts b/packages/turbo-types/src/types/config-v2.ts index 41cc973111c6b..910383bf5ac5d 100644 --- a/packages/turbo-types/src/types/config-v2.ts +++ b/packages/turbo-types/src/types/config-v2.ts @@ -304,6 +304,38 @@ export interface RemoteCache { * @defaultValue `true` */ enabled?: boolean; + + /** + * When enabled, any HTTP request will be preceded by an OPTIONS request to + * determine if the request is supported by the endpoint. + * + * Documentation: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests + * + * @defaultValue `false` + */ + preflight?: boolean; + /** + * Set endpoint for API calls to the remote cache. + * Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting + * + * @defaultValue `"https://vercel.com/api"` + */ + apiUrl?: string; + /** + * Set endpoint for requesting tokens during `turbo login`. + * Documentation: https://turbo.build/repo/docs/core-concepts/remote-caching#self-hosting + * + * @defaultValue `"https://vercel.com"` + */ + loginUrl?: string; + /** + * Sets a timeout for remote cache operations. Value is given in seconds and + * only whole values are accepted. If `0` is passed, then there is no timeout + * for any cache operations. + * + * @defaultValue `30` + */ + timeout?: number; } export const isRootSchemaV2 = (schema: Schema): schema is RootSchema =>