yeti_types/resource/

metadata.rs

//! `ResourceMetadata` — name, routing flags, and permission predicates.
//!
//! this is the read-only view of a resource that
//! the router needs **before** dispatching the request to the resource's
//! `Service<Context>`. Splitting it off the `Resource` trait lets the
//! router store
//!
//! ```ignore
//! struct ResourceEntry {
//!     metadata: Arc<dyn ResourceMetadata>,
//!     service:  BoxCloneSyncService<Context, Response<ResponseBody>, YetiError>,
//! }
//! ```
//!
//! and consult `metadata` for permissions, table-extender wiring, and
//! routing flags without going through any verb-method virtual call.
//!
//! Resources are *internal* services — the dispatch path threads the
//! owned `Context` directly into `Service::call`, avoiding the
//! `TypeId` mismatch that `http::Request::extensions` would impose.

use std::sync::Arc;

use http::Response;

use super::context::Context;
use super::permission::MethodOverrides;
use super::response_body::ResponseBody;
use super::{ConnectionFuture, ResourceFuture, SubscriptionFuture};
use crate::error::YetiError;

/// The non-verb-dispatch surface of a resource. Read-only metadata
/// (name, routing flags, schema-backed attribute list) plus per-verb
/// permission predicates.
///
/// All methods are sync, take `&self`, and read from a borrowed
/// `Context` where they need request state. They never touch the
/// request body or perform I/O.
pub trait ResourceMetadata: Send + Sync + 'static {
    /// Resource name (used in routing).
    fn name(&self) -> &str;

    /// Whether this resource is a default/catch-all handler.
    fn is_default(&self) -> bool {
        false
    }

    /// Return the attribute/field names for this resource (if schema-backed).
    fn attribute_names(&self) -> Option<Arc<Vec<String>>> {
        None
    }

    /// If this resource extends a table, return the table name.
    fn extends_table(&self) -> Option<&str> {
        None
    }

    /// Declare which methods this resource overrides (for table extenders).
    ///
    /// Default: no overrides. Override this in table extender resources to
    /// specify which methods delegate to the custom resource vs. the table.
    fn method_overrides(&self) -> MethodOverrides {
        MethodOverrides::default()
    }

    /// Whether this resource handles the given HTTP method.
    ///
    /// Default: accept all methods (legacy behavior — native Rust resources
    /// match on `ctx.method()` inside their own `Service::call` and return 405
    /// themselves for unsupported verbs). WASM resources override this to
    /// fast-reject routes that don't match their declared `methods` catalog,
    /// avoiding the dispatch round-trip when the verb isn't supported.
    fn supports_method(&self, _method: &http::Method) -> bool {
        true
    }

    // ========================================================================
    // Authorization — reads from Context
    // ========================================================================

    /// Check if this request is allowed to read.
    fn allow_read(&self, ctx: &Context) -> bool {
        if !ctx.access().is_authenticated() {
            return false;
        }
        if ctx.access().is_super_user() {
            return true;
        }
        ctx.access()
            .can_read_table(ctx.database_str(), ctx.table_name_str())
    }

    /// Check if this request is allowed to create.
    fn allow_create(&self, ctx: &Context) -> bool {
        if !ctx.access().is_authenticated() {
            return false;
        }
        if ctx.access().is_super_user() {
            return true;
        }
        let (db, tbl) = ctx.table_context();

        if ctx.is_collection() {
            if !ctx.access().can_insert_table(db, tbl) {
                return false;
            }
            // Check field-level write permissions
            if let Some(obj) = ctx.json_body().and_then(|v| v.as_object()) {
                for key in obj.keys() {
                    if !ctx.access().can_write_attribute(db, tbl, key) {
                        return false;
                    }
                }
            }
            true
        } else {
            self.allow_update(ctx)
        }
    }

    /// Check if this request is allowed to update.
    fn allow_update(&self, ctx: &Context) -> bool {
        if !ctx.access().is_authenticated() {
            return false;
        }
        if ctx.access().is_super_user() {
            return true;
        }
        let (db, tbl) = ctx.table_context();

        if !ctx.access().can_update_table(db, tbl) {
            return false;
        }
        if let Some(obj) = ctx.json_body().and_then(|v| v.as_object()) {
            for key in obj.keys() {
                if !ctx.access().can_write_attribute(db, tbl, key) {
                    return false;
                }
            }
        }
        true
    }

    /// Check if this request is allowed to delete.
    fn allow_delete(&self, ctx: &Context) -> bool {
        if !ctx.access().is_authenticated() {
            return false;
        }
        if ctx.access().is_super_user() {
            return true;
        }
        ctx.access()
            .can_delete_table(ctx.database_str(), ctx.table_name_str())
    }

    /// Check if this request is allowed to subscribe.
    fn allow_subscribe(&self, ctx: &Context) -> bool {
        self.allow_read(ctx)
    }

    /// Check if this request is allowed to connect (WebSocket/SSE).
    fn allow_connect(&self, ctx: &Context) -> bool {
        self.allow_read(ctx)
    }

    /// Whether this resource allows unauthenticated WebSocket/SSE connections.
    ///
    /// This is the no-Context equivalent of `allow_connect` for the public-access
    /// case. The router calls this before constructing a per-request Context so it
    /// can answer "is this a public endpoint?" without a dummy empty-auth Context.
    ///
    /// Default: `false`. Schema-backed resources (`TableResource`) override this
    /// to reflect the `@export(public: [connect])` / `@export(public: [read])`
    /// directive. Custom resources override it when they intend to allow anonymous
    /// WebSocket connections.
    fn is_public_connect(&self) -> bool {
        false
    }

    /// Dispatch an HTTP verb request — the single verb-dispatch entry point.
    ///
    /// ADR-015 merged the former `tower::Service<Context>` impl into this
    /// trait: permissions, realtime, and verb dispatch now live on one
    /// `Resource`. `&self` (not tower's `&mut self`), so the router holds one
    /// `Arc<dyn Resource>` and never clones a boxed service per request.
    ///
    /// Default returns 405 — a metadata-only resource (e.g. a permission-
    /// declaring table extender) inherits it unchanged; resources with verb
    /// bodies (`TableResource`, `WasmResource`, macro output) override it.
    fn handle(&self, _ctx: Context) -> ResourceFuture {
        Box::pin(async {
            #[allow(clippy::expect_used)]
            let resp = Response::builder()
                .status(405)
                .body(ResponseBody::complete(b"Method Not Allowed".to_vec()))
                .expect("static 405 cannot fail to build");
            Ok(resp)
        })
    }

    // ========================================================================
    // Real-time methods — subscribe (SSE) and connect (WebSocket).
    //
    // These take a `Context` rather than a `YetiRequest` because their
    // outputs (`Subscription`, `Connection`) aren't `http::Response`-shaped
    // — they're per-stream / per-socket handles the router holds onto for
    // the lifetime of the connection. Sitting them on `ResourceMetadata`
    // (rather than a separate `Realtime` trait) keeps every resource
    // exposing one interface; defaults return `YetiError::Internal` so
    // resources that don't override appear as "subscribe/connect not
    // supported" rather than silently 200ing.
    // ========================================================================

    /// Subscribe to real-time updates (SSE handler entrypoint).
    fn subscribe(&self, _ctx: Context) -> SubscriptionFuture {
        Box::pin(async {
            Err(YetiError::Internal(
                "subscribe not implemented for this resource".to_owned(),
            ))
        })
    }

    /// Handle WebSocket or SSE connection.
    fn connect(&self, _ctx: Context) -> ConnectionFuture {
        Box::pin(async {
            Err(YetiError::Internal(
                "connect not implemented for this resource".to_owned(),
            ))
        })
    }
}