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

@@ -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);
+    }
 }

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`.

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

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

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 =>