roda-kabk 1.0.0

data/examples/app.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "roda"
+require "sequel"
+require "kabk"
+require "roda/plugins/kabk"
+
+DB = Sequel.sqlite
+DB.extension :pagination
+DB.logger = Logger.new($stdout)
+
+DB.create_table :users do
+  primary_key :id
+  String :full_name
+  String :email
+  String :avatar
+  String :role, default: "editor"
+  String :bio
+  TrueClass :is_active, default: true
+  DateTime :created_at
+  DateTime :updated_at
+end
+
+DB.create_table :categories do
+  primary_key :id
+  String :title
+  String :slug
+  String :color_code
+end
+
+DB.create_table :news_items do
+  primary_key :id
+  String :title
+  Integer :author_id
+  String :category_ids
+  String :cover_image
+  String :gallery
+  String :content
+  TrueClass :published, default: false
+  DateTime :publish_date
+  DateTime :updated_at
+  DateTime :created_at
+end
+
+class User < Sequel::Model; end
+class Category < Sequel::Model; end
+class NewsItem < Sequel::Model; end
+
+Kabk.register(name: "user", table: User) do
+  title en: "User Directory", fa: "مدیریت کاربران"
+  plural_name "users"
+  icon "Users"
+  api_path "/api/admin/users"
+  searchable_fields ["full_name", "email"]
+  sortable_fields ["id", "full_name", "role", "created_at"]
+  concurrency_field "updated_at"
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :full_name, type: :string, form_type: :text, required: true, validation: { min_length: 3, max_length: 100 }
+  field :email, type: :string, form_type: :text, required: true, validation: { unique: true }
+  field :avatar, type: :file, form_type: :image_single, display_as: :thumbnail
+  field :role, type: :string, form_type: :select, required: true, display_as: :badge, default_value: "editor"
+  field :bio, type: :string, form_type: :textarea, hidden_in_table: true, accordion: true
+  field :is_active, type: :boolean, form_type: :switch, display_as: :boolean_icon, default_value: true
+  field :created_at, type: :date, form_type: :date, readonly: true, hidden_in_form: true
+end
+
+Kabk.register(name: "category", table: Category) do
+  title en: "Categories", fa: "دسته‌بندی‌ها"
+  plural_name "categories"
+  icon "Tags"
+  api_path "/api/admin/categories"
+  searchable_fields ["title", "slug"]
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :title, type: :string, form_type: :text, required: true
+  field :slug, type: :string, form_type: :text, required: true
+  field :color_code, type: :string, form_type: :text, display_as: :badge
+end
+
+Kabk.register(name: "news_item", table: NewsItem) do
+  title en: "News & Announcements", fa: "اخبار و اطلاعیه‌ها"
+  plural_name "news"
+  icon "Newspaper"
+  api_path "/api/admin/news"
+  searchable_fields ["title", "content"]
+  concurrency_field "updated_at"
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :title, type: :string, form_type: :text, required: true
+  field :author_id, type: :relation, form_type: :relation_select, relation: { resource: "user", cardinality: "many_to_one", value_field: "id", label_field: "full_name" }
+  field :category_ids, type: :relation, form_type: :multiselect, relation: { resource: "category", cardinality: "many_to_many", value_field: "id", label_field: "title" }
+  field :cover_image, type: :file, form_type: :image_single, display_as: :thumbnail
+  field :content, type: :string, form_type: :wysiwyg, hidden_in_table: true, accordion: true
+  field :published, type: :boolean, form_type: :switch, display_as: :boolean_icon
+  field :publish_date, type: :datetime, form_type: :datetime, depends_on: { field: "published", value: true }
+  field :updated_at, type: :datetime, form_type: :datetime, readonly: true, hidden_in_form: true
+end
+
+User.create(full_name: "Admin User", email: "admin@example.com", role: "admin")
+User.create(full_name: "John Doe", email: "john@example.com", role: "editor")
+Category.create(title: "Announcements", slug: "announcements")
+Category.create(title: "Events", slug: "events")
+NewsItem.create(title: "First Post", author_id: 2, category_ids: "[1,2]", content: "Hello World", updated_at: Time.now)
+
+module AppAuth
+  def self.verify_credentials(email, _password)
+    User.first(email: email)
+  end
+end
+
+def render_root_page
+  <<~HTML
+    <!DOCTYPE html>
+    <html>
+      <head><title>Simurgh Demo</title></head>
+      <body>
+        <h1>Simurgh Admin Demo</h1>
+        <p><a href="/admin">Go to Admin Dashboard</a></p>
+      </body>
+    </html>
+  HTML
+end
+
+class App < Roda
+  plugin :sessions, secret: ENV.fetch("SESSION_SECRET", "super_secret_session_key_longer_than_64_bytes_1234567890")
+  plugin :json
+  plugin :kabk,
+         system_config: {
+           title: { en: "Simurgh Panel", fa: "پنل مدیریت سیمرغ" },
+           default_locale: "en",
+           supported_locales: ["en", "fa"],
+           direction: "ltr",
+           show_demo_credentials: false,
+           logo_url: "/simurgh-logo.svg",
+           endpoints: {
+             upload: "/api/admin/uploads"
+           },
+           auth: {
+             show_demo_credentials: false,
+             login_url: "/api/admin/auth/login",
+             logout_url: "/api/admin/auth/logout",
+             me_url: "/api/admin/auth/me"
+           }
+         }
+
+  route do |r|
+    # Global static assets (CSS, JS, Logo)
+    r.kabk.statics
+
+    # Vue.js SPA Dashboard
+    r.on "admin" do
+      r.is do
+        r.kabk.server
+      end
+
+      r.get do
+        r.kabk.server
+      end
+    end
+
+    # API Backend & Smart Dispatch
+    r.on "api" do
+      r.on "admin" do
+        r.get "schema" do
+          r.kabk.schema
+        end
+
+        r.post "uploads" do
+          r.kabk.upload
+        end
+
+        r.on "auth" do
+          r.post "login" do
+            body = JSON.parse(r.body.read) rescue {}
+            user = AppAuth.verify_credentials(body["email"], body["password"])
+            if user
+              session[:user_id] = user.id
+              { success: true, user: { id: user.id, full_name: user.full_name, email: user.email, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Invalid credentials" } }
+            end
+          end
+
+          r.get "me" do
+            user = User[session[:user_id]]
+            if user
+              { success: true, user: { id: user.id, full_name: user.full_name, email: user.email, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Unauthorized" } }
+            end
+          end
+
+          r.post "logout" do
+            session.clear
+            { success: true, message: "Logged out" }
+          end
+        end
+
+        current_user = User[session[:user_id]]
+        unless current_user
+          response.status = 401
+          r.halt({ success: false, error: { message: "Unauthorized" } }.to_json)
+        end
+
+        r.kabk.route(context: { current_user: current_user })
+      end
+    end
+
+    r.root do
+      render_root_page
+    end
+  end
+end

data/examples/config.ru

@@ -0,0 +1,2 @@
+require_relative "app"
+run App.freeze.app

data/lib/roda/plugins/kabk/helpers.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "json"
+require "kabk"
+require "kabk/rest_engine"
+require "kabk/schema_renderer"
+
+module RodaPlugins
+  module Kabk
+    # Helper object providing Smart Dispatch routing, static asset serving, and utility endpoints for Kabk.
+    class Helpers
+      # Absolute directory path to bundled Simurgh frontend public assets.
+      PUBLIC_DIR = File.expand_path("../../../../public", __dir__)
+
+      # @return [Roda::RodaRequest] The current Roda request instance.
+      attr_reader :request
+
+      # @return [Hash] Configured plugin options.
+      attr_reader :options
+
+      @cached_html = {}
+      @cache_mutex = Mutex.new
+
+      # Clears the cached HTML templates in memory.
+      #
+      # @return [void]
+      def self.reset_cache!
+        @cache_mutex.synchronize { @cached_html.clear }
+      end
+
+      # Returns the memoized index.html content with embedded schema for the given options.
+      #
+      # @param opts [Hash] Plugin configuration options.
+      # @return [String, nil] The processed HTML string or nil if index.html is missing.
+      def self.cached_index_html(opts = {})
+        cache_key = (opts[:system_config] || {}).hash
+        @cache_mutex.synchronize do
+          @cached_html[cache_key] ||= build_index_html(opts)
+        end
+      end
+
+      # Merges default auth and endpoints configuration into system_config.
+      #
+      # @param opts [Hash] Plugin configuration options.
+      # @return [Hash] Normalized system configuration hash.
+      def self.build_system_config(opts = {})
+        raw_config = (opts[:system_config] || {}).dup
+        endpoints = { upload: "/uploads" }.merge(raw_config[:endpoints] || {})
+
+        auth_defaults = {
+          strategy: "session",
+          sso_redirect_url: nil,
+          login_url: "/auth/login",
+          logout_url: "/auth/logout",
+          me_url: "/auth/me",
+          refresh_url: "/auth/refresh",
+          show_demo_credentials: false,
+          login_fields: [
+            {
+              name: "username",
+              label: { en: "Username", fa: "نام کاربری" },
+              placeholder: { en: "Enter your username...", fa: "نام کاربری خود را وارد کنید..." },
+              type: "text",
+              required: true
+            },
+            {
+              name: "password",
+              label: { en: "Password", fa: "کلمه عبور" },
+              placeholder: { en: "Enter your password...", fa: "کلمه عبور خود را وارد کنید..." },
+              type: "password",
+              required: true
+            }
+          ]
+        }
+        auth = auth_defaults.merge(raw_config[:auth] || {})
+
+        base_defaults = {
+          direction: "ltr",
+          default_locale: "en",
+          supported_locales: ["en", "fa"],
+          show_demo_credentials: false
+        }
+
+        base_defaults.merge(raw_config).merge(endpoints: endpoints, auth: auth)
+      end
+
+      # Generates index.html content with injected APP_CONFIG and dynamic schema manifest.
+      #
+      # @param opts [Hash] Plugin configuration options.
+      # @return [String, nil] The transformed HTML string or nil if file not found.
+      def self.build_index_html(opts = {})
+        index_path = File.join(PUBLIC_DIR, "index.html")
+        return nil unless File.file?(index_path)
+
+        content = File.read(index_path)
+        sys_config = build_system_config(opts)
+        schema_renderer = ::Kabk::SchemaRenderer.new(system_config: sys_config)
+        dynamic_schema = schema_renderer.render
+        dynamic_schema_json = JSON.pretty_generate(dynamic_schema)
+
+        content = content.sub(
+          %r{<script id="simurgh-schema" type="application/json">.*?</script>}m,
+          "<script id=\"simurgh-schema\" type=\"application/json\">\n#{dynamic_schema_json}\n    </script>"
+        )
+
+        config_snippet = "window.APP_CONFIG = { baseURL: '' };"
+        content.sub(/window\.APP_CONFIG\s*=\s*\{[^}]*\};/m, config_snippet)
+      end
+
+      # Determines MIME content type based on file extension.
+      #
+      # @param asset_name [String] Name or relative path of the asset.
+      # @return [String] Content-Type header string.
+      def self.asset_content_type(asset_name)
+        case File.extname(asset_name).downcase
+        when ".js" then "application/javascript; charset=utf-8"
+        when ".css" then "text/css; charset=utf-8"
+        when ".svg" then "image/svg+xml"
+        when ".woff2" then "font/woff2"
+        when ".png" then "image/png"
+        when ".ttf" then "font/ttf"
+        when ".mp4" then "video/mp4"
+        when ".webp" then "image/webp"
+        when ".gif" then "image/gif"
+        else "application/octet-stream"
+        end
+      end
+
+      # Initializes a new Helpers instance.
+      #
+      # @param request [Roda::RodaRequest] Current Roda request object.
+      # @param options [Hash] Plugin configuration options.
+      def initialize(request, options = {})
+        @request = request
+        @options = options || {}
+      end
+
+      # Serves global static assets (JS, CSS, Fonts, Images) from the public directory.
+      #
+      # @return [void] Halts the Roda request cycle with the static asset response when matched.
+      def statics
+        request.get "assets", String do |asset_name|
+          asset_path = File.join(PUBLIC_DIR, "assets", asset_name)
+          if File.file?(asset_path)
+            request.response["Content-Type"] = self.class.asset_content_type(asset_name)
+            request.halt [200, request.response.headers, [File.read(asset_path)]]
+          end
+        end
+
+        request.get "simurgh-logo.svg" do
+          logo_path = File.join(PUBLIC_DIR, "simurgh-logo.svg")
+          if File.file?(logo_path)
+            request.response["Content-Type"] = "image/svg+xml"
+            request.halt [200, request.response.headers, [File.read(logo_path)]]
+          end
+        end
+      end
+
+      # Serves the Vue.js SPA index.html dynamically.
+      #
+      # @return [void] Halts the Roda request cycle with the HTML response.
+      def server
+        content = self.class.cached_index_html(options)
+        if content
+          request.response["Content-Type"] = "text/html; charset=utf-8"
+          request.halt [200, request.response.headers, [content]]
+        else
+          handle_errors { raise ::Kabk::NotFoundError, "Simurgh UI index.html not found" }
+        end
+      end
+
+      # Renders and returns the dynamic protocol schema manifest JSON.
+      #
+      # @return [void] Halts the request cycle with JSON response.
+      def schema
+        handle_errors do
+          sys_config = self.class.build_system_config(options)
+          schema_renderer = ::Kabk::SchemaRenderer.new(system_config: sys_config)
+          respond_json(schema_renderer.render)
+        end
+      end
+
+      # Handles multipart file upload requests.
+      #
+      # @return [void] Halts the request cycle with upload JSON response.
+      def upload
+        handle_errors do
+          file_param = request.params["file"] || request.params
+          upload_handler = options[:upload_handler]
+
+          if upload_handler.respond_to?(:call)
+            result = upload_handler.call(file_param, request)
+            respond_json(::Kabk::UploadHandler.format_response(
+              url: result[:url] || result["url"],
+              file_name: result[:file_name] || result["file_name"] || result[:filename] || result["filename"],
+              size: result[:size] || result["size"],
+              mime_type: result[:mime_type] || result["mime_type"]
+            ))
+          elsif file_param.is_a?(Hash) && file_param[:tempfile]
+            respond_json(::Kabk::UploadHandler.format_response(
+              url: "/uploads/#{file_param[:filename]}",
+              file_name: file_param[:filename],
+              size: file_param[:tempfile].size,
+              mime_type: file_param[:type]
+            ))
+          else
+            raise ::Kabk::ValidationError, "No file uploaded or file parameter missing"
+          end
+        end
+      end
+
+      # Dispatches the current HTTP request to the matching registered Kabk resource based on api_path.
+      #
+      # @param context [Hash] Context hash passed to RestEngine lifecycle hooks (e.g. current_user).
+      # @return [void, nil] Halts with the REST response or returns nil if no route matches.
+      def route(context: {})
+        resource, id_param = find_matching_resource
+        return unless resource
+
+        engine = ::Kabk::RestEngine.new(resource.name)
+
+        if id_param.nil? || id_param.empty?
+          if request.get?
+            handle_errors do
+              respond_json(engine.list(request.params, context: context))
+            end
+          elsif request.post?
+            handle_errors do
+              body = parse_json_body
+              respond_json(engine.create(body, context: context))
+            end
+          end
+        else
+          record_id = id_param =~ /\A\d+\z/ ? id_param.to_i : id_param
+
+          if request.get?
+            handle_errors do
+              respond_json(engine.get(record_id, context: context))
+            end
+          elsif request.put? || request.patch?
+            handle_errors do
+              body = parse_json_body
+              respond_json(engine.update(record_id, body, context: context))
+            end
+          elsif request.delete?
+            handle_errors do
+              respond_json(engine.delete(record_id, context: context))
+            end
+          end
+        end
+      end
+
+      private
+
+      # Finds matching Kabk resource from registry based on request path.
+      #
+      # @return [Array(Kabk::Resource, String), nil] Tuple of resource and member ID param, or nil.
+      def find_matching_resource
+        resources = ::Kabk::Registry.instance.all
+        sorted_resources = resources.sort_by { |res| -(res.api_path || "").length }
+
+        path = request.path.chomp("/")
+
+        sorted_resources.each do |res|
+          api_path = res.api_path
+          next if api_path.nil? || api_path.empty?
+
+          norm_api = api_path.start_with?("/") ? api_path : "/#{api_path}"
+          norm_api = norm_api.chomp("/")
+
+          if path == norm_api
+            return [res, nil]
+          elsif path.start_with?("#{norm_api}/")
+            remainder = path.sub("#{norm_api}/", "")
+            return [res, remainder] unless remainder.empty?
+          end
+        end
+        nil
+      end
+
+      # Parses JSON request body safely.
+      #
+      # @return [Hash] Parsed payload hash.
+      def parse_json_body
+        body_str = request.body.read
+        request.body.rewind if request.body.respond_to?(:rewind)
+        return {} if body_str.nil? || body_str.strip.empty?
+
+        JSON.parse(body_str)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Halts the request with a JSON response.
+      #
+      # @param response_hash [Hash] Data to serialize to JSON.
+      # @param status_code [Integer] HTTP status code.
+      # @return [void]
+      def respond_json(response_hash, status_code = 200)
+        request.response.status = status_code
+        request.response["Content-Type"] = "application/json"
+        request.halt [status_code, request.response.headers, [response_hash.to_json]]
+      end
+
+      # Executes the given block and translates Kabk exceptions into standard JSON error responses.
+      #
+      # @yield The block to execute.
+      # @return [Object] Block return value.
+      def handle_errors
+        yield
+      rescue ::Kabk::ValidationError => e
+        err = { code: "VALIDATION_ERROR", message: e.message }
+        err[:fields] = e.fields if e.respond_to?(:fields)
+        respond_json({ success: false, error: err }, 422)
+      rescue ::Kabk::NotFoundError => e
+        respond_json({ success: false, error: { code: "NOT_FOUND", message: e.message } }, 404)
+      rescue StandardError => e
+        if e.class.name.start_with?("Kabk::") && e.respond_to?(:to_h) && e.respond_to?(:http_status)
+          respond_json(e.to_h, e.http_status)
+        else
+          respond_json({ success: false, error: { code: "INTERNAL_SERVER_ERROR", message: e.message } }, 500)
+        end
+      end
+    end
+  end
+end

data/lib/roda/plugins/kabk.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "kabk"
+require_relative "kabk/helpers"
+
+class Roda
+  module RodaPlugins
+    # Kabk plugin for Roda — Smart Dispatch routing and Simurgh Panel integration.
+    #
+    # @example Plugin Registration
+    #   class App < Roda
+    #     plugin :kabk,
+    #            system_config: { logo_url: "/simurgh-logo.svg" },
+    #            upload_handler: ->(file, req) { { url: "/uploads/#{file[:filename]}" } }
+    #   end
+    module Kabk
+      # Loads plugin dependencies into the Roda application.
+      #
+      # @param app [Class<Roda>] The Roda application class.
+      # @param _opts [Hash] Configuration options.
+      # @return [void]
+      def self.load_dependencies(app, _opts = {})
+        app.plugin :all_verbs
+      end
+
+      # Configures the plugin options for the application.
+      #
+      # @param app [Class<Roda>] The Roda application class.
+      # @param opts [Hash] Configuration options.
+      # @option opts [Hash, nil] :system_config Custom system branding and localization configuration.
+      # @option opts [Proc, #call, nil] :upload_handler Custom file upload handler callable.
+      # @return [void]
+      def self.configure(app, opts = {})
+        app.opts[:kabk] ||= {}
+        app.opts[:kabk][:system_config] = opts[:system_config] || nil
+        app.opts[:kabk][:upload_handler] = opts[:upload_handler]
+      end
+
+      # Request methods added to the Roda request instance.
+      module RequestMethods
+        # Returns the Kabk helper object bound to the current request and plugin options.
+        #
+        # @return [RodaPlugins::Kabk::Helpers] Helper object for static assets, SPA server, and Smart Dispatch routing.
+        def kabk
+          options = roda_class.opts[:kabk] || (scope.opts[:kabk] if respond_to?(:scope)) || {}
+          @kabk_helpers ||= ::RodaPlugins::Kabk::Helpers.new(self, options)
+        end
+      end
+    end
+
+    register_plugin(:kabk, Kabk)
+  end
+end