copilot

Author: adamspofford

crates/icp-sync-plugin/sync-plugin.wit

@@ -51,11 +51,19 @@ interface types {
         /// defined directly in the app root has no subproject prefix and appears
         /// as its bare local name, e.g. "backend".
         ///
-        /// Every canister in the same subproject as the canister being synced is
-        /// additionally listed under its bare local name (a duplicate entry with
-        /// the same `id`), so a plugin can address a sibling by the same local
-        /// name the manifest uses. A bare name always means the sibling, so an
-        /// app-root canister sharing that local name is not listed.
+        /// Every canister the subproject being synced can name for itself is
+        /// additionally listed under that name (a duplicate entry with the same
+        /// `id`): its own canisters under their bare local names, and the
+        /// canisters of subprojects nested below it under the
+        /// `subproject:local` key those would have if it were the app root —
+        /// e.g. for "services/crm:backend", the canister
+        /// "services/crm/vendor/ledger:ledger" is also listed as
+        /// "vendor/ledger:ledger". These are the keys the subproject's own
+        /// manifest uses, so a plugin addresses the same canister by the same
+        /// name whether the subproject is deployed standalone or vendored into
+        /// a workspace. Such a name always means what the subproject means by
+        /// it, so a canister elsewhere in the workspace whose key is spelled
+        /// the same way is not listed under it.
         name: string,
         /// Textual principal the name resolves to for this environment.
         id: string,
@@ -71,10 +79,10 @@ interface types {
         /// permitted, whether or not it also appears in `canisters`.
         host,
         /// A canister from the `canisters` list, identified by name, spelled
-        /// exactly as it appears in `sync-exec-input.canister-ids` — a bare
-        /// local name for a canister in the same subproject, or a
-        /// `subproject:local` key otherwise. The host resolves it against that
-        /// mapping table.
+        /// exactly as it appears in `sync-exec-input.canister-ids` — for a
+        /// canister the synced canister's own subproject names, the name that
+        /// subproject uses; otherwise the app-root-relative `subproject:local`
+        /// key. The host resolves it against that mapping table.
         name(string),
     }
 

crates/icp/src/canister/sync/plugin.rs

@@ -158,31 +158,60 @@ pub(super) async fn sync(
 }
 
 /// The canister ID table exposed to a sync plugin: every named canister in the
-/// project, plus — for canisters in the same subproject as the one being synced
-/// — a duplicate entry under the bare local name. A store key is
-/// `<subproject>:<local>` for a canister in a subproject and a bare local name
-/// for a canister defined directly in the app root (see the WIT
-/// `canister-id-entry` docs), so the syncing canister's namespace is the prefix
-/// of its own key.
+/// project, plus — for every canister in the subproject the synced canister
+/// belongs to, or in a subproject nested below it — a duplicate entry under the
+/// name that subproject itself uses. A store key is `<subproject>:<local>` for a
+/// canister in a subproject and a bare local name for a canister defined
+/// directly in the app root (see the WIT `canister-id-entry` docs), so the
+/// syncing canister's namespace is the prefix of its own key.
 ///
-/// A local name never contains a colon but a subproject directory may, so keys
-/// split on their *last* colon. The bare-name aliases take precedence over an
-/// app-root canister of the same local name: a plugin resolving a bare name is
-/// naming what the syncing canister's own manifest calls it.
+/// The aliases exist so a subproject's manifest and plugins keep working when it
+/// is vendored into a workspace: both the step's `canisters:` list and the name a
+/// plugin passes back as a call target are written where the subproject's own
+/// names apply, but store keys are relative to the app root, which moves. See
+/// [`member_relative_alias`] for the names produced.
+///
+/// The aliases take precedence over a canister elsewhere in the workspace whose
+/// store key happens to be spelled the same way: a plugin resolving such a name
+/// is naming what its own subproject calls it.
 fn exposed_canister_ids(params: &Params) -> BTreeMap<String, Principal> {
-    let syncing_namespace = params.name.rsplit_once(':').map(|(namespace, _)| namespace);
+    // A canister in the app root is in the subproject the store keys are already
+    // relative to, so its names need no translation.
+    let Some((syncing_namespace, _)) = params.name.rsplit_once(':') else {
+        return params.canister_ids.clone();
+    };
 
     let mut table = params.canister_ids.clone();
     for (key, id) in &params.canister_ids {
-        if let Some((namespace, local)) = key.rsplit_once(':')
-            && Some(namespace) == syncing_namespace
-        {
-            table.insert(local.to_owned(), *id);
+        if let Some(alias) = member_relative_alias(syncing_namespace, key) {
+            table.insert(alias.to_owned(), *id);
         }
     }
     table
 }
 
+/// The name a canister has *within* the subproject at `namespace`: its store key
+/// with that subproject's prefix removed. A canister of the subproject itself
+/// comes back under its bare local name; one belonging to a subproject nested
+/// below it comes back under the `<path>:<local>` key it would have if that
+/// subproject were the app root. `None` for a canister the subproject has no name
+/// of its own for.
+///
+/// A local name never contains a colon but a subproject directory may, so a key
+/// splits on its *last* colon.
+fn member_relative_alias<'a>(namespace: &str, key: &'a str) -> Option<&'a str> {
+    let (key_namespace, _) = key.rsplit_once(':')?;
+    let rest = key.strip_prefix(namespace)?;
+    match key_namespace == namespace {
+        // The colon separating the subproject from a local name of its own.
+        true => rest.strip_prefix(':'),
+        // Otherwise the key's subproject must sit *below* this one. Demanding
+        // the path separator is what keeps `services/crm-legacy:backend` out of
+        // `services/crm`, which it merely shares a spelling prefix with.
+        false => rest.strip_prefix('/'),
+    }
+}
+
 /// Resolve the step's `canisters` list into a [`CallableCanisters`] enforcement
 /// set. Each listed name is looked up in `canister_ids`; a name that does not
 /// resolve is a manifest error.
@@ -293,6 +322,84 @@ mod tests {
         assert_eq!(table.get("backend"), Some(&backend));
     }
 
+    /// A canister of a subproject nested below the syncing canister's own is
+    /// exposed under the key that subproject has relative to it — the very key
+    /// its manifest and plugins use when it is built standalone, so vendoring it
+    /// into a workspace leaves both spellings working.
+    #[test]
+    fn exposed_ids_add_member_relative_names_for_nested_subprojects() {
+        let ledger = principal(1);
+        let deep = principal(2);
+        let params = params_named(
+            "services/crm:backend",
+            &[
+                ("services/crm:backend", principal(9)),
+                ("services/crm/vendor/ledger:ledger", ledger),
+                ("services/crm/vendor/ledger/vendor/util:util", deep),
+            ],
+        );
+
+        let table = exposed_canister_ids(&params);
+
+        assert_eq!(table.get("vendor/ledger:ledger"), Some(&ledger));
+        // Nesting is not limited to one level: the whole subtree below the
+        // syncing canister's subproject is renamed relative to it.
+        assert_eq!(table.get("vendor/ledger/vendor/util:util"), Some(&deep));
+        // The workspace-absolute keys remain.
+        assert_eq!(
+            table.get("services/crm/vendor/ledger:ledger"),
+            Some(&ledger)
+        );
+    }
+
+    /// A subproject whose path merely starts with the same characters is not
+    /// nested below the syncing canister's, so it contributes no alias.
+    #[test]
+    fn exposed_ids_ignore_a_subproject_sharing_a_spelling_prefix() {
+        let legacy = principal(1);
+        let params = params_named(
+            "services/crm:backend",
+            &[
+                ("services/crm:backend", principal(9)),
+                ("services/crm-legacy:backend", legacy),
+            ],
+        );
+
+        let table = exposed_canister_ids(&params);
+
+        assert_eq!(table.get("services/crm-legacy:backend"), Some(&legacy));
+        // Its local name belongs to the syncing canister, not to it.
+        assert_eq!(table.get("backend"), Some(&principal(9)));
+        assert_eq!(table.get("-legacy:backend"), None);
+    }
+
+    /// A member-relative alias wins over a workspace canister whose store key is
+    /// spelled the same way, for the same reason a bare sibling name does: the
+    /// name is being read where the subproject's own names apply.
+    #[test]
+    fn exposed_ids_member_relative_alias_overrides_a_root_dependency_key() {
+        let root_ledger = principal(1);
+        let own_ledger = principal(2);
+        let params = params_named(
+            "services/crm:backend",
+            &[
+                ("services/crm:backend", principal(9)),
+                ("services/crm/vendor/ledger:ledger", own_ledger),
+                ("vendor/ledger:ledger", root_ledger),
+            ],
+        );
+
+        let table = exposed_canister_ids(&params);
+
+        assert_eq!(table.get("vendor/ledger:ledger"), Some(&own_ledger));
+        // The root's own dependency is still reachable, by its store key.
+        assert_eq!(
+            table.get("services/crm/vendor/ledger:ledger"),
+            Some(&own_ledger)
+        );
+        assert!(!table.values().any(|id| *id == root_ledger));
+    }
+
     /// An app-root canister sharing a local name with a sibling of the syncing
     /// canister does not keep the bare name: the syncing subproject's own
     /// canister is what that name means to the plugin.
@@ -323,18 +430,41 @@ mod tests {
     fn exposed_ids_split_subproject_prefix_at_the_last_colon() {
         let backend = principal(1);
         let frontend = principal(2);
+        let nested = principal(3);
         let params = params_named(
             "services/odd:name:backend",
             &[
                 ("services/odd:name:backend", backend),
                 ("services/odd:name:frontend", frontend),
+                ("services/odd:name/vendor/ledger:ledger", nested),
             ],
         );
 
         let table = exposed_canister_ids(&params);
 
         assert_eq!(table.get("backend"), Some(&backend));
         assert_eq!(table.get("frontend"), Some(&frontend));
+        assert_eq!(table.get("vendor/ledger:ledger"), Some(&nested));
+    }
+
+    /// The mirror image: a directory whose *name* contains a colon is not a
+    /// subproject nested below the part before it. `services/odd:name` holds one
+    /// directory named `odd:name`, so from `services/odd` it is nothing at all.
+    #[test]
+    fn exposed_ids_do_not_read_a_colon_in_a_directory_name_as_nesting() {
+        let odd = principal(1);
+        let params = params_named(
+            "services/odd:backend",
+            &[
+                ("services/odd:backend", principal(9)),
+                ("services/odd:name:frontend", odd),
+            ],
+        );
+
+        let table = exposed_canister_ids(&params);
+
+        assert_eq!(table.get("services/odd:name:frontend"), Some(&odd));
+        assert_eq!(table.get("name:frontend"), None);
     }
 
     /// A single-project layout keys canisters by bare local name already, so no

crates/icp/src/manifest/adapter/plugin.rs

@@ -261,11 +261,14 @@ pub struct Adapter {
 
     /// Canisters this plugin may call, or read metadata from, in addition to
     /// the canister being synced. Each entry is a canister name resolved against
-    /// the project's canister ID table for the environment being synced (e.g.
-    /// `backend`, or a namespaced subproject canister such as
-    /// `services/open-crm:backend`). The plugin picks a target per request via
-    /// the `call-target` in its `canister-call` or `canister-metadata-section`
-    /// request; a target not listed here is rejected by the host.
+    /// the project's canister ID table for the environment being synced, written
+    /// as this project spells it: a bare local name for one of its own canisters
+    /// (e.g. `backend`), or a `<subproject>:<canister>` key for a canister of
+    /// something it depends on (e.g. `vendor/ledger:ledger`). The same spellings
+    /// hold when the project is a workspace member, so vendoring it does not
+    /// change them. The plugin picks a target per request via the `call-target`
+    /// in its `canister-call` or `canister-metadata-section` request; a target
+    /// not listed here is rejected by the host.
     pub canisters: Option<Vec<String>>,
 }
 

docs/concepts/sync-plugins.md

@@ -78,7 +78,9 @@ The authoritative interface, including all record fields, lives in [`sync-plugin
 | `proxy-canister-id` | Textual principal of the proxy canister if one was configured via `--proxy`, otherwise absent |
 | `canister-ids` | The project's canister ID table for this environment — each entry a canister name and the principal it resolves to. Informational; being listed here does not grant permission to call a canister |
 
-Each `canister-ids` entry's name is the canister's fully-qualified project key: a bare local name for a canister defined in the app root, or a `subproject:canister` key for a canister defined in a subproject. Canisters in the same subproject as the one being synced are additionally listed under their bare local name, so a plugin can look up a sibling by the name that subproject's manifest uses. A bare name always means the sibling: if an app-root canister has the same local name, it is not listed for that sync.
+Each `canister-ids` entry's name is the canister's fully-qualified project key: a bare local name for a canister defined in the app root, or a `subproject:canister` key for a canister defined in a subproject.
+
+Every canister the subproject being synced can name for itself is additionally listed under that name, so a plugin looks a canister up by the name that subproject's own manifest uses. For a canister in `services/crm`, that means its siblings under their bare local names, and the canisters of its own dependencies under keys relative to it — `services/crm/vendor/ledger:ledger` is also listed as `vendor/ledger:ledger`. Those are the names the subproject uses when it is deployed on its own, so a plugin written against them keeps working once the subproject is vendored into a workspace. Such a name always means what the subproject means by it: a canister elsewhere in the workspace whose key is spelled the same way is not listed under it for that sync.
 
 The manifest declares directories and files together under `files:`; the host splits them into these two lists by what is on disk, so a plugin never has to say up front which an entry will turn out to be.
 

docs/guides/writing-sync-plugins.md

@@ -85,7 +85,7 @@ export!(Plugin);
 A few things to note:
 
 - **You encode the arguments.** `arg` is raw Candid bytes. Encode with `candid::Encode!`; decode any response (`Vec<u8>`) with `candid::Decode!`.
-- **You choose the target.** `target: CallTarget::Host` reaches the canister being synced. To call another canister, declare it in the manifest's [`canisters:`](../reference/configuration.md#plugin-sync) list and address it with `CallTarget::Name("ledger".into())` — the name matches the entries in `input.canister_ids`. Names are the only way to reach another canister; the host resolves them per environment. The host rejects a target you did not declare.
+- **You choose the target.** `target: CallTarget::Host` reaches the canister being synced. To call another canister, declare it in the manifest's [`canisters:`](../reference/configuration.md#plugin-sync) list and address it with `CallTarget::Name("ledger".into())` — the name matches the entries in `input.canister_ids`. Names are the only way to reach another canister; the host resolves them per environment. The host rejects a target you did not declare. A name is always the one the plugin's own project uses, so hardcoding it stays correct when that project is vendored into a workspace as a subproject.
 - **`direct` and `cycles` control proxy routing.** With `direct: false`, update calls go through the [proxy canister](proxy-canister.md) when one is configured, and `cycles` can fund the forwarded call. With `direct: true`, the call always goes straight to the target. See [The Plugin Interface](../concepts/sync-plugins.md#the-plugin-interface) for the full semantics.
 
 ## Read Canister Metadata

docs/reference/configuration.md

@@ -207,6 +207,8 @@ A plugin receives every `fields:` value as a string. Numbers and booleans need n
 
 A canister name in `canisters:` is the same name you use elsewhere in the project — a bare local name for a sibling canister, or a namespaced `subproject:canister` key for a canister defined in a subproject. A name that does not resolve to a known canister for the environment fails the sync step.
 
+Names are always written from this project's point of view, so they keep working when the project is vendored into a workspace as a subproject: a plugin on a canister in `services/crm` reaches a canister of its own `vendor/ledger` dependency as `vendor/ledger:ledger` either way, even though the workspace keys that canister `services/crm/vendor/ledger:ledger`. Both spellings resolve; if a canister elsewhere in the workspace happens to be keyed `vendor/ledger:ledger`, the name means your own.
+
 The plugin runs in a WASI sandbox: it can call update and query methods on the canister being synced (and any canister listed in `canisters:`), read those canisters' metadata sections, and read the declared `files`, but cannot open network sockets, spawn subprocesses, or write to disk. See [Sync Plugins](../concepts/sync-plugins.md) for the mechanism and [Writing a Sync Plugin](../guides/writing-sync-plugins.md) to author one.
 
 ## Recipes