Add first component paths (#25416)

The general idea is that I'll change our function execution layers to accept a `ComponentFunctionPath` and then only support `ComponentId::Root` for now.

GitOrigin-RevId: 2a53e96a98bfd3b62082737b448e43e3981c0928

Author: Sujay Jayakar

crates/common/src/components/component_definition_path.rs

@@ -0,0 +1,68 @@
+use std::{
+    ops::Deref,
+    path::{
+        Component as PathComponent,
+        PathBuf,
+    },
+    str::FromStr,
+};
+
+use anyhow::Context;
+use sync_types::path::check_valid_path_component;
+
+// Path relative to a project's `convex/` directory for each component
+// definition's folder. This path is project-level and originates from
+// a developer's source code.
+pub struct ComponentDefinitionPath {
+    path: PathBuf,
+}
+
+impl FromStr for ComponentDefinitionPath {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let path = PathBuf::from(s);
+        for component in path.components() {
+            match component {
+                PathComponent::Normal(c) => {
+                    let s = c
+                        .to_str()
+                        .context("Path {s} has an invalid Unicode character")?;
+                    check_valid_path_component(s)?;
+                },
+                // Component paths are allowed to have `..` (since they're relative from the root
+                // component's source directory).
+                PathComponent::ParentDir => (),
+                PathComponent::RootDir => {
+                    anyhow::bail!("Component paths must be relative ({s} is absolute).")
+                },
+                c => anyhow::bail!("Invalid path component {c:?} in {s}."),
+            }
+        }
+        path.as_os_str()
+            .to_str()
+            .context("Path {s} has an invalid Unicode character")?;
+        Ok(ComponentDefinitionPath { path })
+    }
+}
+
+impl Deref for ComponentDefinitionPath {
+    type Target = str;
+
+    fn deref(&self) -> &Self::Target {
+        self.path
+            .as_os_str()
+            .to_str()
+            .expect("Invalid Unicode in ComponentDefinitionPath")
+    }
+}
+
+impl From<ComponentDefinitionPath> for String {
+    fn from(value: ComponentDefinitionPath) -> Self {
+        value
+            .path
+            .into_os_string()
+            .into_string()
+            .expect("Invalid Unicode in ComponentDefinitionPath?")
+    }
+}

crates/common/src/components/component_path.rs

@@ -0,0 +1,16 @@
+// All components under a component have a unique `ComponentName`. For example,
+// the root app component may have a waitlist component identified by
+// "chatWaitlist".
+#[allow(unused)]
+pub struct ComponentName {
+    name: String,
+}
+
+// Path within the component tree for a particular component. Note that this
+// path can potentially change when the component tree changes during a push, so
+// developers should resolve this path to a `ComponentId` within a transaction
+// as soon as possible.
+#[allow(unused)]
+pub struct ComponentPath {
+    path: Vec<ComponentName>,
+}

crates/common/src/components/function_paths.rs

@@ -0,0 +1,24 @@
+use sync_types::{
+    CanonicalizedUdfPath,
+    UdfPath,
+};
+
+use super::{
+    component_definition_path::ComponentDefinitionPath,
+    ComponentId,
+};
+
+pub struct ComponentDefinitionFunctionPath {
+    pub component: ComponentDefinitionPath,
+    pub udf_path: UdfPath,
+}
+
+pub struct ComponentFunctionPath {
+    pub component: ComponentId,
+    pub udf_path: UdfPath,
+}
+
+pub struct CanonicalizedComponentFunctionPath {
+    pub component: ComponentId,
+    pub udf_path: CanonicalizedUdfPath,
+}

crates/common/src/components/mod.rs

@@ -0,0 +1,24 @@
+use value::InternalDocumentId;
+
+mod component_definition_path;
+mod component_path;
+mod function_paths;
+
+pub use self::{
+    component_definition_path::ComponentDefinitionPath,
+    component_path::{
+        ComponentName,
+        ComponentPath,
+    },
+    function_paths::{
+        CanonicalizedComponentFunctionPath,
+        ComponentDefinitionFunctionPath,
+        ComponentFunctionPath,
+    },
+};
+
+// Globally unique system-assigned ID for a component.
+pub enum ComponentId {
+    Root,
+    Child(InternalDocumentId),
+}

crates/common/src/lib.rs

@@ -32,6 +32,7 @@ pub mod bounds;
 pub mod client_pool;
 pub mod codel_queue;
 pub mod comparators;
+pub mod components;
 pub mod deleted_bitset;
 pub mod document;
 pub mod errors;

crates/convex/sync_types/src/lib.rs

@@ -4,6 +4,7 @@ pub mod headers;
 pub mod identifier;
 pub mod json;
 pub mod module_path;
+pub mod path;
 #[cfg(any(test, feature = "testing"))]
 pub mod testing;
 pub mod timestamp;

crates/convex/sync_types/src/module_path.rs

@@ -7,7 +7,7 @@ use std::{
     str::FromStr,
 };
 
-use crate::identifier::MAX_IDENTIFIER_LEN;
+use crate::path::check_valid_path_component;
 
 pub const SYSTEM_UDF_DIR: &str = "_system";
 pub const DEPS_DIR: &str = "_deps";
@@ -100,28 +100,6 @@ fn canonicalize_path_buf(mut path: PathBuf) -> PathBuf {
     path
 }
 
-fn check_valid_path_component(s: &str) -> anyhow::Result<()> {
-    if s.len() > MAX_IDENTIFIER_LEN {
-        anyhow::bail!(
-            "Path component is too long ({} > maximum {}).",
-            s.len(),
-            MAX_IDENTIFIER_LEN
-        );
-    }
-    if !s
-        .chars()
-        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.')
-    {
-        anyhow::bail!(
-            "Path component {s} can only contain alphanumeric characters, underscores, or periods."
-        );
-    }
-    if !s.chars().any(|c| c.is_ascii_alphanumeric()) {
-        anyhow::bail!("Path component {s} must have at least one alphanumeric character.");
-    }
-    Ok(())
-}
-
 /// Parse a module path from a `str`.
 impl FromStr for ModulePath {
     type Err = anyhow::Error;

crates/convex/sync_types/src/path.rs

@@ -0,0 +1,23 @@
+use crate::identifier::MAX_IDENTIFIER_LEN;
+
+pub fn check_valid_path_component(s: &str) -> anyhow::Result<()> {
+    if s.len() > MAX_IDENTIFIER_LEN {
+        anyhow::bail!(
+            "Path component is too long ({} > maximum {}).",
+            s.len(),
+            MAX_IDENTIFIER_LEN
+        );
+    }
+    if !s
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.')
+    {
+        anyhow::bail!(
+            "Path component {s} can only contain alphanumeric characters, underscores, or periods."
+        );
+    }
+    if !s.chars().any(|c| c.is_ascii_alphanumeric()) {
+        anyhow::bail!("Path component {s} must have at least one alphanumeric character.");
+    }
+    Ok(())
+}