From 2e05e6f40d2b8a5d5312f73f9b7522809a107da5 Mon Sep 17 00:00:00 2001 From: t4lz Date: Mon, 23 Oct 2023 10:20:44 +0200 Subject: [PATCH] Clarify exceptions in FS config docs (#2021) * clarify in docs * CR: note * CR: not_found description Co-authored-by: Eyal Bukchin * CR: unrelated doc mistake * update schema * lint --------- Co-authored-by: Eyal Bukchin --- changelog.d/2020.fixed.md | 1 + mirrord-schema.json | 2 +- mirrord/config/src/feature/fs/advanced.rs | 24 ++++++++++++++++++++--- 3 files changed, 23 insertions(+), 4 deletions(-) create mode 100644 changelog.d/2020.fixed.md diff --git a/changelog.d/2020.fixed.md b/changelog.d/2020.fixed.md new file mode 100644 index 00000000000..ea1aeda6e47 --- /dev/null +++ b/changelog.d/2020.fixed.md @@ -0,0 +1 @@ +Clarify more about the pre-defined FS exceptions in docs, link to lists. diff --git a/mirrord-schema.json b/mirrord-schema.json index 0fb57c1599e..64da9e5f269 100644 --- a/mirrord-schema.json +++ b/mirrord-schema.json @@ -140,7 +140,7 @@ "additionalProperties": false, "definitions": { "AdvancedFsUserConfig": { - "description": "Allows the user to specify the default behavior for file operations:\n\n1. `\"read\"` - Read from the remote file system (default) 2. `\"write\"` - Read/Write from the remote file system. 3. `\"local\"` - Read from the local file system. 5. `\"disable\"` - Disable file operations.\n\nBesides the default behavior, the user can specify behavior for specific regex patterns. Case insensitive.\n\n1. `\"read_write\"` - List of patterns that should be read/write remotely. 2. `\"read_only\"` - List of patterns that should be read only remotely. 3. `\"local\"` - List of patterns that should be read locally. 4. `\"not_found\"` - List of patters that should never be read nor written. These files should be treated as non-existent.\n\nThe logic for choosing the behavior is as follows:\n\n1. Check if one of the patterns match the file path, do the corresponding action. There's no specified order if two lists match the same path, we will use the first one (and we do not guarantee what is first).\n\n**Warning**: Specifying the same path in two lists is unsupported and can lead to undefined behaviour.\n\n2. Check our \"special list\" - we have an internal at compile time list for different behavior based on patterns to provide better UX.\n\n3. If none of the above match, use the default behavior (mode).\n\nFor more information, check the file operations [technical reference](https://mirrord.dev/docs/reference/fileops/).\n\n```json { \"feature\": { \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\.json\" , \"read_only\": [ \".+\\.yaml\", \".+important-file\\.txt\" ], \"local\": [ \".+\\.js\", \".+\\.mjs\" ], \"not_found\": [ \"\\.config/gcloud\" ] } } } ```", + "description": "Allows the user to specify the default behavior for file operations:\n\n1. `\"read\"` - Read from the remote file system (default) 2. `\"write\"` - Read/Write from the remote file system. 3. `\"local\"` - Read from the local file system. 4. `\"localwithoverrides\"` - perform fs operation locally, unless the path matches a pre-defined or user-specified exception.\n\n> Note: by default, some paths are read locally or remotely, regardless of the selected FS mode. > This is described in further detail below.\n\nBesides the default behavior, the user can specify behavior for specific regex patterns. Case insensitive.\n\n1. `\"read_write\"` - List of patterns that should be read/write remotely. 2. `\"read_only\"` - List of patterns that should be read only remotely. 3. `\"local\"` - List of patterns that should be read locally. 4. `\"not_found\"` - List of patters that should never be read nor written. These files should be treated as non-existent.\n\nThe logic for choosing the behavior is as follows:\n\n1. Check if one of the patterns match the file path, do the corresponding action. There's no specified order if two lists match the same path, we will use the first one (and we do not guarantee what is first).\n\n**Warning**: Specifying the same path in two lists is unsupported and can lead to undefined behaviour.\n\n2. There are pre-defined exceptions to the set FS mode. a. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs) are read locally by default. b. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_remote_by_default.rs) are read remotely by default when the mode is `localwithoverrides`. c. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/not_found_by_default.rs) under the running user's home directory will not be found by the application when the mode is not `local`. In order to override that default setting for a path, or a pattern, include it the appropriate pattern set from above. E.g. in order to read files under `/etc/` remotely even though it is covered by [the set of patterns that are read locally by default](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs), add `\"^/etc/.\"` to the `read_only` set.\n\n3. If none of the above match, use the default behavior (mode).\n\nFor more information, check the file operations [technical reference](https://mirrord.dev/docs/reference/fileops/).\n\n```json { \"feature\": { \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\.json\" , \"read_only\": [ \".+\\.yaml\", \".+important-file\\.txt\" ], \"local\": [ \".+\\.js\", \".+\\.mjs\" ], \"not_found\": [ \"\\.config/gcloud\" ] } } } ```", "type": "object", "properties": { "local": { diff --git a/mirrord/config/src/feature/fs/advanced.rs b/mirrord/config/src/feature/fs/advanced.rs index ae2c5076866..6d52dd18857 100644 --- a/mirrord/config/src/feature/fs/advanced.rs +++ b/mirrord/config/src/feature/fs/advanced.rs @@ -17,7 +17,11 @@ use crate::{ /// 1. `"read"` - Read from the remote file system (default) /// 2. `"write"` - Read/Write from the remote file system. /// 3. `"local"` - Read from the local file system. -/// 5. `"disable"` - Disable file operations. +/// 4. `"localwithoverrides"` - perform fs operation locally, unless the path matches a pre-defined +/// or user-specified exception. +/// +/// > Note: by default, some paths are read locally or remotely, regardless of the selected FS mode. +/// > This is described in further detail below. /// /// Besides the default behavior, the user can specify behavior for specific regex patterns. /// Case insensitive. @@ -37,8 +41,22 @@ use crate::{ /// **Warning**: Specifying the same path in two lists is unsupported and can lead to undefined /// behaviour. /// -/// 2. Check our "special list" - we have an internal at compile time list -/// for different behavior based on patterns to provide better UX. +/// 2. There are pre-defined exceptions to the set FS mode. +/// a. Paths that match +/// [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs) +/// are read locally by default. +/// b. Paths that match +/// [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_remote_by_default.rs) +/// are read remotely by default when the mode is `localwithoverrides`. +/// c. Paths that match +/// [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/not_found_by_default.rs) +/// under the running user's home directory will not be found by the application when the mode +/// is not `local`. +/// In order to override that default setting for a path, or a pattern, include it the appropriate +/// pattern set from above. E.g. in order to read files under `/etc/` remotely even though it is +/// covered by +/// [the set of patterns that are read locally by default](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs), +/// add `"^/etc/."` to the `read_only` set. /// /// 3. If none of the above match, use the default behavior (mode). ///