appstruct-codegen 0.2.0

Deterministic Rust, SQL, OpenAPI, TypeScript, and React generation for AppStruct
Documentation
use super::render;
use crate::{Artifact, ArtifactKind, CodegenError};
use appstruct_ir::{AppIr, FileProviderIr};
use quote::quote;

pub(super) fn plan(ir: &AppIr) -> Result<Vec<Artifact>, CodegenError> {
    let source = if ir.file.enabled {
        enabled_source(ir)?
    } else {
        disabled_source()?
    };
    Ok(vec![Artifact::text(
        "backend/src/file.rs",
        source,
        ArtifactKind::RustSource,
    )])
}

fn enabled_source(ir: &AppIr) -> Result<String, CodegenError> {
    let (provider_source, provider_init) = provider_source(ir);
    let contract = contract_source();
    let state = state_source(
        &provider_init,
        &ir.file.allowed_content_types,
        ir.file.max_bytes,
    );
    let metadata = metadata_source();
    let validation = validation_source();
    let lifecycle = lifecycle_source(ir)?;
    render(quote! {
        use async_trait::async_trait;
        use object_store::{
            ObjectStore, ObjectStoreExt, PutMode, PutOptions, PutPayload,
            path::Path as ObjectPath,
        };
        use sqlx::Row as _;
        use crate::database::{DatabaseExecutor, Database,  DbErr, Sql};
        use std::{env, fmt, path::{Component, Path}, sync::Arc};
        #contract
        #state
        #metadata
        #validation
        #lifecycle
        #provider_source
    })
}

fn contract_source() -> proc_macro2::TokenStream {
    quote! {
        #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
        pub struct FileMetadata {
            pub id: uuid::Uuid,
            pub object_key: String,
            pub original_name: String,
            pub content_type: String,
            pub size: u64,
            pub checksum: String,
            pub tenant_id: Option<uuid::Uuid>,
            pub created_at: chrono::DateTime<chrono::Utc>,
        }
        #[derive(Debug)]
        pub enum FileError {
            Disabled, InvalidKey, InvalidName, InvalidContentType,
            TooLarge { size: u64, max: u64 }, Configuration(String),
            Storage(String), Database(DbErr), ReferenceConflict,
        }
        impl fmt::Display for FileError {
            fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
                match self {
                    Self::ReferenceConflict => formatter.write_str("file is unavailable, referenced, deleting, or has too many owners"),
                    Self::Disabled => formatter.write_str("file module is disabled"),
                    Self::InvalidKey => formatter.write_str("file key must be a safe relative path"),
                    Self::InvalidName => formatter.write_str("file name is invalid"),
                    Self::InvalidContentType => formatter.write_str("file content does not match an allowed content type"),
                    Self::TooLarge { size, max } => write!(formatter, "file is too large: {size} bytes exceeds {max}"),
                    Self::Configuration(error) => write!(formatter, "file configuration is invalid: {error}"),
                    Self::Storage(error) => write!(formatter, "file storage operation failed: {error}"),
                    Self::Database(error) => write!(formatter, "file metadata operation failed: {error}"),
                }
            }
        }
        impl std::error::Error for FileError {}
        impl From<DbErr> for FileError { fn from(error: DbErr) -> Self { Self::Database(error) } }
        #[async_trait]
        pub trait FileProvider: Send + Sync {
            fn name(&self) -> &'static str;
            async fn put(&self, object_key: &str, content: &[u8]) -> Result<(), FileError>;
            async fn get(&self, object_key: &str) -> Result<Vec<u8>, FileError>;
            async fn delete(&self, object_key: &str) -> Result<(), FileError>;
        }
    }
}

fn state_source(
    provider_init: &proc_macro2::TokenStream,
    allowed: &[String],
    max_bytes: u64,
) -> proc_macro2::TokenStream {
    let allowed = allowed.iter().map(|value| quote! { #value.to_owned() });
    quote! {
        #[derive(Clone)]
        pub struct FileState {
            database: Database,
            provider: Arc<dyn FileProvider>,
            allowed_content_types: Arc<Vec<String>>,
        }
        impl FileState {
            pub fn from_env(database: Database) -> Result<Self, FileError> {
                let provider = #provider_init;
                Ok(Self {
                    database, provider,
                    allowed_content_types: Arc::new(vec![#(#allowed),*]),
                })
            }
            pub fn with_provider(
                database: Database, provider: Arc<dyn FileProvider>,
                allowed_content_types: Vec<String>,
            ) -> Self {
                Self { database, provider, allowed_content_types: Arc::new(allowed_content_types) }
            }
            pub async fn put(
                &self, object_key: &str, original_name: &str, content_type: &str,
                content: &[u8], tenant_id: Option<uuid::Uuid>,
            ) -> Result<FileMetadata, FileError> {
                self.put_with_connection(
                    &self.database, object_key, original_name, content_type, content, tenant_id,
                ).await
            }
            pub(crate) async fn put_with_connection<C: DatabaseExecutor>(
                &self, database: &C, object_key: &str, original_name: &str, content_type: &str,
                content: &[u8], tenant_id: Option<uuid::Uuid>,
            ) -> Result<FileMetadata, FileError> {
                validate_key(object_key)?;
                validate_name(original_name)?;
                let size = u64::try_from(content.len()).unwrap_or(u64::MAX);
                if size > #max_bytes { return Err(FileError::TooLarge { size, max: #max_bytes }); }
                validate_content(content_type, content, &self.allowed_content_types)?;
                let checksum = appstruct_runtime::sha256_hex(content);
                self.provider.put(object_key, content).await?;
                match insert_metadata(
                    database, object_key, original_name, content_type, size, &checksum, tenant_id,
                ).await {
                    Ok(metadata) => Ok(metadata),
                    Err(error) => {
                        let _ = self.provider.delete(object_key).await;
                        Err(error)
                    }
                }
            }
            pub async fn get(
                &self, object_key: &str, tenant_id: Option<uuid::Uuid>,
            ) -> Result<(FileMetadata, Vec<u8>), FileError> {
                self.get_with_connection(&self.database, object_key, tenant_id).await
            }
            pub(crate) async fn get_with_connection<C: DatabaseExecutor>(
                &self, database: &C, object_key: &str, tenant_id: Option<uuid::Uuid>,
            ) -> Result<(FileMetadata, Vec<u8>), FileError> {
                validate_key(object_key)?;
                let metadata = load_metadata(database, object_key, tenant_id).await?;
                let content = self.provider.get(object_key).await?;
                if appstruct_runtime::sha256_hex(&content) != metadata.checksum {
                    return Err(FileError::Storage("stored object checksum does not match metadata".to_owned()));
                }
                Ok((metadata, content))
            }
            #[allow(dead_code)]
            pub(crate) async fn discard_unpublished<C: DatabaseExecutor>(&self, database: &C, object_key: &str) -> Result<(), FileError> {
                validate_key(object_key)?;
                let metadata = database.fetch_optional(Sql::bind( "SELECT id FROM \"_appstruct_files\" WHERE object_key = $1", [object_key.to_owned().into()],
                )).await?;
                if metadata.is_none() { self.provider.delete(object_key).await?; }
                Ok(())
            }
            pub async fn delete(
                &self, object_key: &str, tenant_id: Option<uuid::Uuid>,
            ) -> Result<(), FileError> {
                let transaction = self.database.begin().await?;
                let result = self.delete_with_connection(&transaction, object_key, tenant_id).await;
                transaction.commit().await?;
                result
            }
            pub(crate) async fn delete_with_connection(
                &self, database: &crate::database::Transaction, object_key: &str, tenant_id: Option<uuid::Uuid>,
            ) -> Result<(), FileError> {
                validate_key(object_key)?;
                let claimed = database.execute(Sql::bind(
                    "UPDATE \"_appstruct_files\" SET deleting = true WHERE object_key = $1 AND tenant_id IS NOT DISTINCT FROM $2 AND reference_owners = '[]'::jsonb",
                    [object_key.to_owned().into(), tenant_id.into()],
                )).await?;
                if claimed.rows_affected() == 0 { return Err(FileError::ReferenceConflict); }
                self.remove_claimed(database, object_key).await
            }
        }
    }
}

fn metadata_source() -> proc_macro2::TokenStream {
    quote! {
        async fn insert_metadata<C: DatabaseExecutor>(
            database: &C, object_key: &str, original_name: &str,
            content_type: &str, size: u64, checksum: &str, tenant_id: Option<uuid::Uuid>,
        ) -> Result<FileMetadata, FileError> {
            let id = uuid::Uuid::now_v7();
            let row = database.fetch_optional(Sql::bind("INSERT INTO \"_appstruct_files\" (id, object_key, original_name, content_type, size, checksum, tenant_id, created_at) VALUES ($1, $2, $3, $4, $5, $6, $7, CURRENT_TIMESTAMP) RETURNING id, object_key, original_name, content_type, size, checksum, tenant_id, created_at",
                [id.into(), object_key.to_owned().into(), original_name.to_owned().into(), content_type.to_owned().into(), i64::try_from(size).unwrap_or(i64::MAX).into(), checksum.to_owned().into(), tenant_id.into()],
            )).await?.ok_or_else(|| DbErr::Protocol("file metadata insert returned no row".to_owned()))?;
            row_to_metadata(row).map_err(FileError::from)
        }
        async fn load_metadata<C: DatabaseExecutor>(
            database: &C, object_key: &str, tenant_id: Option<uuid::Uuid>,
        ) -> Result<FileMetadata, FileError> {
            let row = database.fetch_optional(Sql::bind("SELECT id, object_key, original_name, content_type, size, checksum, tenant_id, created_at FROM \"_appstruct_files\" WHERE object_key = $1 AND tenant_id IS NOT DISTINCT FROM $2",
                [object_key.to_owned().into(), tenant_id.into()],
            )).await?.ok_or_else(|| DbErr::RowNotFound)?;
            row_to_metadata(row).map_err(FileError::from)
        }
        fn row_to_metadata(row: crate::database::PgRow) -> Result<FileMetadata, DbErr> {
            Ok(FileMetadata {
                id: row.try_get("id")?, object_key: row.try_get("object_key")?,
                original_name: row.try_get("original_name")?, content_type: row.try_get("content_type")?,
                size: row.try_get::<i64, _>("size")?.try_into().unwrap_or_default(),
                checksum: row.try_get("checksum")?, tenant_id: row.try_get("tenant_id")?,
                created_at: row.try_get("created_at")?,
            })
        }
    }
}

fn validation_source() -> proc_macro2::TokenStream {
    quote! {
        fn validate_key(value: &str) -> Result<(), FileError> {
            if value.is_empty() || value.len() > 512 || value.contains('\\') || value.contains('\0')
                || Path::new(value).is_absolute()
                || value.split('/').any(|segment| segment.is_empty() || matches!(segment, "." | ".."))
                || Path::new(value).components().any(|part| !matches!(part, Component::Normal(_))) {
                return Err(FileError::InvalidKey);
            }
            Ok(())
        }
        fn validate_name(value: &str) -> Result<(), FileError> {
            if value.is_empty() || matches!(value, "." | "..") || value.len() > 255
                || value.contains('/') || value.contains('\\')
                || value.chars().any(char::is_control) {
                Err(FileError::InvalidName)
            } else { Ok(()) }
        }
        fn validate_content(
            content_type: &str, content: &[u8], allowed: &[String],
        ) -> Result<(), FileError> {
            let allowed = allowed.iter().any(|candidate| {
                candidate == content_type || (candidate.ends_with("/*")
                    && content_type.starts_with(&candidate[..candidate.len() - 1]))
            });
            if !allowed { return Err(FileError::InvalidContentType); }
            let valid = if content_type == "application/octet-stream" {
                true
            } else if content_type == "application/json" {
                serde_json::from_slice::<serde_json::Value>(content).is_ok()
            } else if content_type.starts_with("text/") {
                !content.contains(&0) && std::str::from_utf8(content).is_ok()
            } else {
                infer::get(content).is_some_and(|kind| kind.mime_type() == content_type)
            };
            if valid { Ok(()) } else { Err(FileError::InvalidContentType) }
        }
    }
}

fn provider_source(ir: &AppIr) -> (proc_macro2::TokenStream, proc_macro2::TokenStream) {
    let source = object_store_provider();
    let init = match ir.file.provider {
        FileProviderIr::Local => {
            let root = &ir.file.local_root;
            quote! {{
                let root = env::var("APPSTRUCT_FILE_ROOT").unwrap_or_else(|_| #root.to_owned());
                std::fs::create_dir_all(&root).map_err(|error| FileError::Configuration(error.to_string()))?;
                let store = object_store::local::LocalFileSystem::new_with_prefix(root)
                    .map_err(|error| FileError::Configuration(error.to_string()))?;
                Arc::new(ObjectStoreProvider { provider_name: "local", store: Arc::new(store) })
                    as Arc<dyn FileProvider>
            }}
        }
        FileProviderIr::S3 => quote! {{
            let required = |name: &str| env::var(name)
                .map_err(|_| FileError::Configuration(format!("{name} is required")));
            let endpoint = required("APPSTRUCT_S3_ENDPOINT")?;
            let allow_http = env::var("APPSTRUCT_S3_ALLOW_HTTP").as_deref() == Ok("true");
            let store = object_store::aws::AmazonS3Builder::new()
                .with_bucket_name(required("APPSTRUCT_S3_BUCKET")?)
                .with_endpoint(endpoint)
                .with_access_key_id(required("APPSTRUCT_S3_ACCESS_KEY")?)
                .with_secret_access_key(required("APPSTRUCT_S3_SECRET_KEY")?)
                .with_region(env::var("APPSTRUCT_S3_REGION").unwrap_or_else(|_| "us-east-1".to_owned()))
                .with_allow_http(allow_http)
                .build().map_err(|error| FileError::Configuration(error.to_string()))?;
            Arc::new(ObjectStoreProvider { provider_name: "s3", store: Arc::new(store) })
                as Arc<dyn FileProvider>
        }},
    };
    (source, init)
}

fn object_store_provider() -> proc_macro2::TokenStream {
    quote! {
        struct ObjectStoreProvider {
            provider_name: &'static str,
            store: Arc<dyn ObjectStore>,
        }
        #[async_trait]
        impl FileProvider for ObjectStoreProvider {
            fn name(&self) -> &'static str { self.provider_name }
            async fn put(&self, object_key: &str, content: &[u8]) -> Result<(), FileError> {
                let options = PutOptions { mode: PutMode::Create, ..PutOptions::default() };
                self.store.put_opts(
                    &ObjectPath::from(object_key), PutPayload::from(content.to_vec()), options,
                )
                    .await.map(|_| ()).map_err(|error| FileError::Storage(error.to_string()))
            }
            async fn get(&self, object_key: &str) -> Result<Vec<u8>, FileError> {
                self.store.get(&ObjectPath::from(object_key)).await
                    .map_err(|error| FileError::Storage(error.to_string()))?.bytes().await
                    .map(|bytes| bytes.to_vec()).map_err(|error| FileError::Storage(error.to_string()))
            }
            async fn delete(&self, object_key: &str) -> Result<(), FileError> {
                match self.store.delete(&ObjectPath::from(object_key)).await {
                    Ok(()) | Err(object_store::Error::NotFound { .. }) => Ok(()),
                    Err(error) => Err(FileError::Storage(error.to_string())),
                }
            }
        }
    }
}

fn disabled_source() -> Result<String, CodegenError> {
    render(quote! {
        use crate::database::{DatabaseExecutor, Database};
        use std::{fmt, sync::Arc};
        #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)] pub struct FileMetadata;
        #[derive(Debug)] pub enum FileError { Disabled }
        impl fmt::Display for FileError { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { formatter.write_str("file module is disabled") } }
        impl std::error::Error for FileError {}
        #[async_trait::async_trait] pub trait FileProvider: Send + Sync {}
        #[derive(Clone, Default)] pub struct FileState;
        impl FileState {
            pub fn from_env(_database: Database) -> Result<Self, FileError> { Ok(Self) }
            pub fn with_provider(_database: Database, _provider: Arc<dyn FileProvider>, _allowed_content_types: Vec<String>) -> Self { Self }
            pub async fn put(&self, _key: &str, _name: &str, _content_type: &str, _content: &[u8], _tenant_id: Option<uuid::Uuid>) -> Result<FileMetadata, FileError> { Err(FileError::Disabled) }
            pub(crate) async fn put_with_connection<C: DatabaseExecutor>(&self, _database: &C, _key: &str, _name: &str, _content_type: &str, _content: &[u8], _tenant_id: Option<uuid::Uuid>) -> Result<FileMetadata, FileError> { Err(FileError::Disabled) }
            pub async fn get(&self, _key: &str, _tenant_id: Option<uuid::Uuid>) -> Result<(FileMetadata, Vec<u8>), FileError> { Err(FileError::Disabled) }
            pub(crate) async fn get_with_connection<C: DatabaseExecutor>(&self, _database: &C, _key: &str, _tenant_id: Option<uuid::Uuid>) -> Result<(FileMetadata, Vec<u8>), FileError> { Err(FileError::Disabled) }
            pub(crate) async fn retain_with_connection<C: DatabaseExecutor>(&self, _database: &C, _key: &str, _entity: &str, _record_id: &str, _tenant: Option<uuid::Uuid>) -> Result<(), FileError> { Err(FileError::Disabled) }
            pub(crate) async fn release_with_connection<C: DatabaseExecutor>(&self, _database: &C, _key: &str, _entity: &str, _record_id: &str, _tenant: Option<uuid::Uuid>) -> Result<(), FileError> { Err(FileError::Disabled) }
            pub async fn delete(&self, _key: &str, _tenant_id: Option<uuid::Uuid>) -> Result<(), FileError> { Err(FileError::Disabled) }
            pub(crate) async fn delete_with_connection(&self, _database: &crate::database::Transaction, _key: &str, _tenant_id: Option<uuid::Uuid>) -> Result<(), FileError> { Err(FileError::Disabled) }
        }
    })
}

fn lifecycle_source(ir: &AppIr) -> Result<proc_macro2::TokenStream, CodegenError> {
    let mut conditions = String::new();
    if ir.report.enabled {
        conditions.push_str(" AND NOT EXISTS (SELECT 1 FROM \"_appstruct_report_runs\" r WHERE r.result_file_id = f.id)");
    }
    if ir.activity.enabled {
        conditions.push_str(" AND NOT EXISTS (SELECT 1 FROM \"_appstruct_activity_entries\" a WHERE a.attachment_file_id = f.id)");
    }
    let sql = format!(
        r#"WITH candidates AS (
        SELECT f.id FROM "_appstruct_files" f
        WHERE f.reference_owners = '[]'::jsonb
          AND (f.deleting OR f.unreferenced_at < CURRENT_TIMESTAMP - $1 * INTERVAL '1 day')
          {conditions}
        ORDER BY f.unreferenced_at, f.id LIMIT $2 FOR UPDATE OF f SKIP LOCKED
    ) UPDATE "_appstruct_files" f SET deleting = true FROM candidates c
      WHERE f.id = c.id RETURNING f.object_key"#
    );
    include_str!("../../templates/backend/file_lifecycle.rs")
        .replace("__APPSTRUCT_FILE_COLLECTION_SQL__", &format!("{sql:?}"))
        .parse()
        .map_err(|error| CodegenError::new(format!("invalid file lifecycle source: {error}")))
}