kabk 1.0.0

data/lib/kabk/schema_renderer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Kabk
+  # Renders the JSON Schema manifest for the protocol v1.6.0
+  class SchemaRenderer
+    # Initializes the schema renderer
+    #
+    # @param system_config [Hash, nil] Optional system config overrides (e.g., title, logo_url, endpoints)
+    # @param validation_schema_url [String, nil] Custom URL for the validation schema
+    def initialize(system_config: nil, validation_schema_url: nil)
+      @system_config = system_config ? default_system_config.merge(system_config) : default_system_config
+      @validation_schema_url = validation_schema_url || "/schemas/admin-protocol-1.6.0.json"
+    end
+
+    def render
+      {
+        "$schema_version": "1.6.0",
+        system: @system_config,
+        validation_schema_url: @validation_schema_url,
+        resources: Registry.instance.all.map(&:to_h)
+      }
+    end
+
+    private
+
+    def default_system_config
+      {
+        title: { fa: "پنل مدیریت سیمرغ", en: "Simurgh Panel" },
+        logo_url: "/simurgh-logo.svg",
+        default_locale: "en",
+        supported_locales: %w[en fa],
+        direction: "ltr",
+        endpoints: {
+          upload: "/api/admin/uploads"
+        },
+        custom_fonts: [
+          {
+            name: "Lalezar",
+            url: "https://fonts.gstatic.com/s/lalezar/v14/OpUp1a5dqj36gZ2zXh_WfQ.woff2",
+            format: "woff2",
+            label: { en: "Lalezar (Title)", fa: "لاله‌زار (عنوان)" }
+          },
+          {
+            name: "Sahel",
+            url: "https://cdn.jsdelivr.net/gh/rastikerdar/sahel-font@v3.4.0/dist/Sahel.woff2",
+            format: "woff2",
+            label: { en: "Sahel (Clean)", fa: "ساحل (خوانا)" }
+          }
+        ],
+        custom_font_sizes: [
+          {
+            size: "15px",
+            label: { en: "Medium Fine (15px)", fa: "متوسط ظریف (۱۵px)" }
+          },
+          {
+            size: "20px",
+            label: { en: "Sub-heading (20px)", fa: "زیرعنوان (۲۰px)" }
+          },
+          {
+            size: "32px",
+            label: { en: "Hero Display (32px)", fa: "تیتر برجسته (۳۲px)" }
+          }
+        ]
+      }
+    end
+  end
+end

data/lib/kabk/upload_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Handles generic file uploads and formats them according to Protocol v1.6.0
+  class UploadHandler
+    # @param url [String] Public URL of the uploaded file
+    # @param file_name [String] Original file name
+    # @param size [Integer] File size in bytes
+    # @param mime_type [String] File mime type
+    # @return [Hash] Formatted upload response
+    def self.format_response(url:, file_name:, size:, mime_type: nil)
+      {
+        success: true,
+        message: "File uploaded successfully",
+        data: {
+          url: url,
+          file_name: file_name,
+          size: size,
+          mime_type: mime_type || "application/octet-stream"
+        }
+      }
+    end
+  end
+end

data/lib/kabk/validator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Kabk
+  # Handles input sanitization (strong parameters) and validation
+  class Validator
+    # Sanitizes input parameters against defined fields and validates them
+    # @param resource [Kabk::Resource]
+    # @param params [Hash] Request payload
+    # @param is_update [Boolean] Is this a PUT/update request?
+    # @return [Hash] Sanitized parameters ready for the database adapter
+    def self.validate_and_sanitize!(resource, params, is_update: false)
+      sanitized = {}
+      errors = {}
+
+      resource.fields.each do |field|
+        next if field.primary_key || field.readonly
+
+        key_sym = field.name.to_sym
+        key_str = field.name.to_s
+        has_key = params.key?(key_sym) || params.key?(key_str)
+        value = params.key?(key_sym) ? params[key_sym] : params[key_str]
+
+        field_errors = validate_field(field, value, has_key, is_update)
+        errors[key_str] = field_errors unless field_errors.empty?
+
+        sanitized[key_sym] = value if has_key
+      end
+
+      # Ensure the concurrency field is included for OCC validation.
+      if resource.concurrency_field
+        c_field = resource.concurrency_field
+        sanitized[c_field.to_sym] = params[c_field.to_sym] || params[c_field.to_s] if params.key?(c_field.to_sym) || params.key?(c_field.to_s)
+      end
+
+      raise ValidationError.new(fields: errors) unless errors.empty?
+
+      sanitized
+    end
+
+    def self.validate_field(field, value, has_key, is_update)
+      rules = field.validation.is_a?(Hash) ? field.validation : nil
+
+      if field.required
+        return [resolve_message(rules, "This field is required")] if !has_key && !is_update
+        return [resolve_message(rules, "This field is required")] if has_key && (value.nil? || value.to_s.strip.empty?)
+      end
+
+      return [] unless has_key && !value.nil? && rules
+
+      collect_rule_errors(field, rules, value)
+    end
+
+    def self.collect_rule_errors(field, rules, value)
+      errs = []
+
+      if field.type.to_s == "string" && value.is_a?(String)
+        len_err = validate_string_length(rules, value)
+        errs << len_err if len_err
+      end
+
+      if (rules[:pattern] || rules["pattern"]) && value.is_a?(String)
+        pat_err = validate_pattern(rules, value)
+        errs << pat_err if pat_err
+      end
+
+      if field.type.to_s == "number"
+        num_err = validate_numeric_range(rules, value)
+        errs << num_err if num_err
+      end
+
+      errs
+    end
+
+    def self.validate_string_length(rules, value)
+      min_len = rules[:min_length] || rules["min_length"]
+      max_len = rules[:max_length] || rules["max_length"]
+
+      return resolve_message(rules, "Minimum length is #{min_len}") if min_len && value.length < min_len
+      return resolve_message(rules, "Maximum length is #{max_len}") if max_len && value.length > max_len
+
+      nil
+    end
+
+    def self.validate_pattern(rules, value)
+      pattern = rules[:pattern] || rules["pattern"]
+      return nil unless pattern
+
+      regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+      return nil if regex.match?(value)
+
+      resolve_message(rules, "Does not match the required format")
+    end
+
+    def self.validate_numeric_range(rules, value)
+      min = rules[:min] || rules["min"]
+      max = rules[:max] || rules["max"]
+      return nil unless min || max
+
+      num = parse_numeric(value)
+      return nil unless num
+
+      return resolve_message(rules, "Minimum value is #{min}") if min && num < min
+      return resolve_message(rules, "Maximum value is #{max}") if max && num > max
+
+      nil
+    end
+
+    def self.parse_numeric(value)
+      return value if value.is_a?(Numeric)
+      return nil unless value.is_a?(String) && value =~ /\A-?\d+(\.\d+)?\z/
+
+      value.include?(".") ? value.to_f : value.to_i
+    end
+
+    def self.resolve_message(rules, default_message)
+      rules&.dig(:custom_message) || rules&.dig("custom_message") || default_message
+    end
+  end
+end

data/lib/kabk/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Kabk module namespace
+module Kabk
+  VERSION = "1.0.0"
+end

data/lib/kabk.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "kabk/version"
+require_relative "kabk/registry"
+require_relative "kabk/resource"
+require_relative "kabk/field"
+require_relative "kabk/resource_builder"
+require_relative "kabk/schema_renderer"
+require_relative "kabk/errors"
+require_relative "kabk/concurrency"
+require_relative "kabk/validator"
+require_relative "kabk/query_builder"
+require_relative "kabk/relation_hydrator"
+require_relative "kabk/rest_engine"
+require_relative "kabk/upload_handler"
+require_relative "kabk/adapters/base"
+require_relative "kabk/adapters/sequel_adapter"
+
+# Core namespace and entrypoint for Kabk
+module Kabk
+  # Register a new model as a resource
+  #
+  # @param name [String, Symbol] The unique identifier for the resource
+  # @param table [Class] The Model class (e.g. Sequel::Model)
+  # @param adapter [Kabk::Adapters::Base] Optional explicit adapter instance
+  # @yield Block evaluated in the context of a ResourceBuilder
+  def self.register(name:, table:, adapter: nil, &block)
+    resource = Resource.new(name: name, model_class: table)
+    builder = ResourceBuilder.new(resource)
+    builder.instance_eval(&block) if block_given?
+
+    # Fallbacks per protocol
+    resource.plural_name ||= "#{name}s"
+    resource.title ||= resource.plural_name.capitalize
+    resource.icon ||= "Database"
+    resource.api_path ||= "/api/admin/#{resource.plural_name}"
+
+    # Determine and assign adapter
+    if adapter
+      resource.adapter = adapter
+    elsif defined?(Sequel::Model) && table < Sequel::Model
+      resource.adapter = Adapters::SequelAdapter.new(resource)
+    else
+      raise ArgumentError, "Could not determine appropriate adapter for #{table}. Please provide an explicit adapter."
+    end
+
+    Registry.instance.register(resource)
+    resource
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: kabk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Parham Taheri
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Framework-agnostic engine that provides resource registration, JSON schema
+  manifest generation, generic CRUD engine, server-side validation, and relation hydration.
+email:
+- Par_taheri@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- Kabk_logo.svg
+- LICENSE
+- README.md
+- doc/Kabk.html
+- doc/Kabk/Adapters.html
+- doc/Kabk/Adapters/Base.html
+- doc/Kabk/Adapters/SequelAdapter.html
+- doc/Kabk/ApiError.html
+- doc/Kabk/Auth.html
+- doc/Kabk/Auth/JwtStrategy.html
+- doc/Kabk/Concurrency.html
+- doc/Kabk/ConcurrencyConflictError.html
+- doc/Kabk/Error.html
+- doc/Kabk/ExportHandler.html
+- doc/Kabk/Field.html
+- doc/Kabk/ForbiddenError.html
+- doc/Kabk/InvalidFieldError.html
+- doc/Kabk/InvalidOldPasswordError.html
+- doc/Kabk/NotFoundError.html
+- doc/Kabk/QueryBuilder.html
+- doc/Kabk/Registry.html
+- doc/Kabk/RelationHydrator.html
+- doc/Kabk/Resource.html
+- doc/Kabk/ResourceBuilder.html
+- doc/Kabk/RestEngine.html
+- doc/Kabk/SchemaRenderer.html
+- doc/Kabk/UnauthorizedError.html
+- doc/Kabk/UploadHandler.html
+- doc/Kabk/ValidationError.html
+- doc/Kabk/Validator.html
+- doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file_list.html
+- doc/frames.html
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
+- docs/API_REFERENCE.md
+- lib/kabk.rb
+- lib/kabk/adapters/base.rb
+- lib/kabk/adapters/sequel_adapter.rb
+- lib/kabk/concurrency.rb
+- lib/kabk/errors.rb
+- lib/kabk/field.rb
+- lib/kabk/query_builder.rb
+- lib/kabk/registry.rb
+- lib/kabk/relation_hydrator.rb
+- lib/kabk/resource.rb
+- lib/kabk/resource_builder.rb
+- lib/kabk/rest_engine.rb
+- lib/kabk/schema_renderer.rb
+- lib/kabk/upload_handler.rb
+- lib/kabk/validator.rb
+- lib/kabk/version.rb
+homepage: https://github.com/par-taheri/Kabk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/par-taheri/Kabk
+  source_code_uri: https://github.com/par-taheri/Kabk
+  changelog_uri: https://github.com/par-taheri/Kabk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Core engine for Schema-Driven Dynamic Admin Specification (Protocol v1.6.0).
+test_files: []