glib-web 7.0.0.beta1 → 7.0.1.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38b655bd80465e224c8ed56c8e63694af4786e89a4028da3915737bf8ac96120
-  data.tar.gz: 6baa89e800c1223673fe1d9bbad61694e6a59c46123f42faff344d819e143dbf
+  metadata.gz: 7a88117fbaf57f748a21abf1ea95fc18fdec09171c7b93e87ac8ef5e02850f93
+  data.tar.gz: d37adcb5e04c61400b5f073ada5a65d0cd5e5f39b62df49c3a28c93c93b06a41
 SHA512:
-  metadata.gz: 30a1adca1ba187b2f23ff52f54b41259742e15582abf95404b07b658e6eb4a408e2a236b8ffe7b4b45459e7ad3abfb9f8017e8701887fe5b4f5028d045834d23
-  data.tar.gz: c4645773a9b5aea3d3b3ba0aea2e24c609e09b45bc7b4904b76bad3af3dd486ed9b4b1b38dba4b956da4620656127462970a1b73c960c231a21da42685fd6f71
+  metadata.gz: a47b8e5826f8ac505d0e38b4530a9294140dcd8e5280178c636e2abe78d38d4c323a04d02e0915aec9bcaf73441fecb90d5d0f89650059e7cdc9a7658f737b56
+  data.tar.gz: 7c8ce8df263b855e5a09cd4e42d5e0bf039c0b24d9d08b1f6f6767e5d8857f4cd33d1f9b5a272f3a4c8b8aa16291ff26c57f4dfa350d8881d5b79129dd77f2be

data/app/controllers/concerns/glib/auth/policy.rb

@@ -22,7 +22,11 @@ module Glib::Auth
       # - Need to find a solution where we can reuse a single public policy
       # after_action :verify_authorized
 
-      helper_method :policy, :can?, :cannot?
+      # Guarded because not every includer has `helper_method`: ActionController::Base
+      # does, but bare ActionController::API does not (gems like jbuilder may include
+      # ActionController::Helpers into it in a booted app, and a plain non-controller
+      # class never has it). Same guard Pundit's own included block uses.
+      helper_method :policy, :can?, :cannot? if respond_to?(:helper_method)
     end
 
     def assert_current_user_present

data/app/controllers/concerns/glib/auth/token_authenticatable.rb

@@ -0,0 +1,37 @@
+module Glib::Auth
+  # Bearer-token authentication for machine-facing APIs. The token's storage column and
+  # the user model are app-specific, so the lookup is a template method the app's base
+  # controller implements (return the user for a valid token, nil otherwise).
+  module TokenAuthenticatable
+    extend ActiveSupport::Concern
+
+    # Public to mirror the browser side, where Devise's current_user is public: glib
+    # hands policies the controller (Glib::ApplicationPolicy#controller), and host-app
+    # policies call these with an EXPLICIT receiver (`controller.current_user`,
+    # `delegate :user_signed_in?, to: :controller`). A private current_user would raise
+    # NoMethodError on the API line only -- the two surfaces must behave the same.
+    def current_user
+      @current_user
+    end
+
+    # Provided by Devise's helpers on the browser side; defined here so glib policies
+    # that delegate it to the controller work unchanged on API controllers.
+    def user_signed_in?
+      current_user.present?
+    end
+
+    private
+      def authenticate_api_token!
+        token = request.headers['Authorization'].to_s.sub(/\ABearer\s+/i, '')
+        @current_user = glib_find_user_by_api_token(token) if token.present?
+        return if @current_user
+
+        render json: { error: 'unauthorized' }, status: :unauthorized
+      end
+
+      # App implements: return the user for a valid token, nil otherwise.
+      def glib_find_user_by_api_token(_token)
+        raise NotImplementedError, "#{self.class} must define glib_find_user_by_api_token(token)"
+      end
+  end
+end

data/app/controllers/glib/api_controller.rb

@@ -0,0 +1,52 @@
+# The ApplicationController analog for agent- or machine-facing JSON APIs.
+#
+# Posture (do not re-derive it from a sibling app):
+# - The Bearer token IS the credential; possession decides authentication. There is
+#   deliberately no cookie/session path in: ActionController::API has no CSRF protection,
+#   so a cookie-authenticated write endpoint here would be a CSRF target. Do not add one.
+# - Authorization works exactly as on the browser side: policies decide, one per resource,
+#   derived by `glib_authorize_resource` from the controller name (override with
+#   `class:` when the derived name is wrong, as on any glib controller).
+# - Every subclass defines `glib_load_resource` (glib has no default) and is covered by a
+#   policy, including index-only controllers (define it as a no-op there).
+# - Opt OUT of authentication with `skip_before_action :authenticate_api_token!` for a
+#   public endpoint; never opt in ad hoc.
+#
+# Callback order is declaration order and is load-bearing:
+#   authenticate_api_token! -> glib_load_resource -> glib_authorize_resource
+# Token auth is declared before glib_auth_init so no request can reach record loading or
+# authorization unauthenticated. Keep the includes in that order in subclasses too.
+#
+# Unhandled exceptions keep Rails' default error body, which is HTML in development
+# unless the app is api-only. Consumers wanting JSON there should set
+# `config.debug_exception_response_format = :api` or add their own
+# `rescue_from` (the browser side's json_libs_rescue_500 does this for the same reason).
+class Glib::ApiController < ActionController::API
+  include Glib::Auth::TokenAuthenticatable
+  before_action :authenticate_api_token!
+
+  include Glib::Auth::Policy
+  glib_auth_init
+
+  rescue_from ActiveRecord::RecordNotFound do
+    render json: { error: 'not found' }, status: :not_found
+  end
+
+  rescue_from ActiveRecord::RecordInvalid do |e|
+    render json: { errors: e.record.errors }, status: :unprocessable_entity
+  end
+
+  rescue_from ActionController::ParameterMissing do
+    render json: { error: 'bad request' }, status: :bad_request
+  end
+
+  # The parent class, not Glib::Auth::Policy::UnauthorizedError: this covers both glib's
+  # raise sites (the subclass) and Pundit's own authorize(), which raises the parent --
+  # otherwise a consumer calling authorize() would get a 500 instead of JSON.
+  rescue_from Pundit::NotAuthorizedError do
+    # Token auth halts unauthenticated requests earlier, so this is normally 403;
+    # keep the 401 branch so the class is safe if a subclass skips token auth.
+    status = current_user ? :forbidden : :unauthorized
+    render json: { error: status.to_s }, status: status
+  end
+end

data/app/helpers/glib/json_ui/view_builder/fields.rb

@@ -211,6 +211,51 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Timing options for the `onChange` / `onChangeAndLoad` actions of fields
+    # whose value changes while the user is still typing.
+    #
+    # Honoured by the single-line text family (text, number, email, url,
+    # password -- all one Vue component) and by textarea. Other fields ignore
+    # them: the discrete ones (check, radio, select, chip group, date pickers)
+    # commit a value the moment it is picked, and richText/phone/file keep
+    # their own reporting. The options are declared on `Text`, so its other
+    # subclasses accept them without effect -- same as `leftIcon` and
+    # `onTypeStart` there.
+    #
+    # In both modes the change is also reported when focus leaves the field.
+    # Under `input` that only flushes a change already pending in the debounce
+    # window -- it cannot produce a second run, because a value that was
+    # already reported is not reported again.
+    module ChangeTrigger
+      def self.included(base)
+        # When the `onChange` / `onChangeAndLoad` actions fire.
+        #
+        # - `input` (default): after the user pauses typing for `changeDelay`.
+        # - `blur`: only once focus leaves the field. Use for actions too
+        #   expensive to run mid-word -- a server round trip, a recalculation
+        #   that rewrites other fields under the user's cursor.
+        #
+        # @example Round-trip only once the user is done with the field
+        #   form.fields_text \
+        #     name: 'user[promo_code]',
+        #     label: 'Promo code',
+        #     changeOn: 'blur',
+        #     onChange: ->(action) { action.http_get url: verify_promo_path }
+        base.enum :changeOn, options: %w[input blur]
+
+        # Milliseconds of no typing before `changeOn: 'input'` fires.
+        # Defaults to 300. Ignored under `changeOn: 'blur'`.
+        #
+        # @example Slow down a search-as-you-type round trip
+        #   form.fields_text \
+        #     name: 'q',
+        #     label: 'Search',
+        #     changeDelay: 800,
+        #     onChange: ->(action) { action.http_get url: search_path }
+        base.int :changeDelay
+      end
+    end
+
     # Basic text input field for single-line text entry.
     #
     # The most common field type, supporting various customizations like
@@ -228,6 +273,8 @@ class Glib::JsonUi::ViewBuilder
     #
     # @see app/views/json_ui/garage/forms/basic.json.jbuilder Garage example
     class Text < AbstractField
+      include ChangeTrigger
+
       # Maximum number of characters allowed.
       int :maxLength
 
@@ -659,7 +706,10 @@ class Glib::JsonUi::ViewBuilder
     class ChipGroup < AbstractField
       color :color
       array :options
-      bool :multiple
+      # cache: true for the same reason as Upload's — without it a
+      # multiple-selection ChipGroup submits under a single key and only the
+      # last selected value survives server-side parsing.
+      bool :multiple, cache: true
     end
 
     class TimeZone < AbstractField
@@ -797,7 +847,11 @@ class Glib::JsonUi::ViewBuilder
       include Glib::JsonUi::FileUploadErrorHandler
 
       action :onFinishUpload
-      bool :multiple
+      # cache: true so `@multiple` is set before AbstractField#created computes
+      # the submit key — without it the `[]` array suffix is dropped and a
+      # multi-file submit collapses to the last file server-side (silently
+      # saves one Document per drop instead of one per file).
+      bool :multiple, cache: true
       hash :placeholderView, required: [:type, :width, :height], optional: [:url]
       hash :inputView, optional: [:files, :variant]
       hash :clipboardView, optional: [:icon]
@@ -855,13 +909,88 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Signature field that lets the user draw a signature on a canvas and
+    # upload it as an image via ActiveStorage direct upload.
+    #
+    # The form shows a placeholder sized by `width`/`height`; tapping it opens
+    # a dialog with the drawing canvas, and Confirm uploads the drawing as a
+    # PNG to `directUploadUrl` and submits the resulting signed id under
+    # `name`. The placeholder then shows the signature, and reopening the
+    # dialog lets the user edit it. Because the canvas is not in the form,
+    # the placeholder can be given the same height as a neighbouring input
+    # (e.g. a typed-name alternative) without losing drawing space.
+    #
+    # `label` titles the dialog; `placeholder` replaces the "Tap to sign"
+    # prompt.
+    #
+    # With `typedName` the dialog gains Draw/Type tabs: the user can type
+    # their name instead of drawing, and the placeholder then shows the name
+    # in a handwriting style (the `glib-sign-typed` hook carries the font).
+    # The typed name is submitted under `typedName[:name]`; exactly one of the
+    # signed id and the typed name is ever non-blank. `typedName[:value]`
+    # pre-populates an existing name.
+    #
+    # @example Basic signature field
+    #   form.fields_sign \
+    #     name: 'user[signature]',
+    #     label: 'Your signature',
+    #     directUploadUrl: glib_direct_uploads_url,
+    #     width: 320,
+    #     height: 160,
+    #     validation: { required: { message: 'add your signature!' } }
+    #
+    # @example Drawn or typed
+    #   form.fields_sign \
+    #     name: 'user[signature]',
+    #     label: 'Your signature',
+    #     typedName: { name: 'user[signature_name]', label: 'Type your full name', placeholder: 'Full name' },
+    #     directUploadUrl: glib_direct_uploads_url,
+    #     width: 320,
+    #     height: 160
+    #
+    # @example Compact signature without validation
+    #   form.fields_sign \
+    #     id: 'signature_compact',
+    #     name: 'user[signature_compact]',
+    #     directUploadUrl: glib_direct_uploads_url,
+    #     width: 220,
+    #     height: 100
+    #
+    # @note A saved signature is a signed id that cannot be redrawn from the
+    #   canvas: when a record is re-edited the field pre-populates `value`
+    #   with the existing attachment's signed id (the component renders a
+    #   read-only preview instead of ink). An untouched field therefore
+    #   re-submits that same signed id, so consumers should treat a
+    #   same-signed-id re-attach as "no change". Resize it via
+    #   `components_set`/`logics_set` with `width`/`height`.
+    #
+    # @see app/views/json_ui/garage/test_page/fields_sign.json.jbuilder Garage examples
     class Sign < AbstractField
       string :directUploadUrl
       required :directUploadUrl
 
+      # URL of an already-attached signature image to display as a read-only
+      # preview (typically `file_url(attachment)` when re-editing a record
+      # that has a drawn signature). Pair with `prop:` so the field also
+      # submits the existing signed id when left untouched.
+      string :fileUrl
+
+      # Enables the Type tab. `value` pre-populates the previously typed
+      # name; `label`/`placeholder` decorate the text input in the dialog.
+      # `name` is still accepted but unused: the typed name is submitted
+      # through the field's own param (single-param contract), and the
+      # server routes it to the name attribute.
+      hash :typedName, optional: [:name, :value, :label, :placeholder]
+
       # Override
-      # Signature field doesn't have default value
-      def value(value)
+      # A stored signature is an attachment -- submit its signed id (mirrors
+      # File#determine_value) so re-editing a signed submission pre-fills the
+      # field with the existing blob's signed id instead of serializing the
+      # whole attachment proxy.
+      def determine_value(context, prop)
+        if (value = context.field_value(prop)).attached?
+          value.signed_id || ''
+        end
       end
     end
 

data/app/jobs/glib/purge_unattached_job.rb

@@ -0,0 +1,32 @@
+module Glib
+  # Daily cleanup for ActiveStorage blobs that have no attachments. Excludes blobs referenced by
+  # any `SnapshotBlobReference` row, so old file versions that still appear in some snapshot's
+  # timeline (i.e. a previous version of an attached file) survive the purge.
+  #
+  # Opt-in: if the host app has not run the gem's `create_snapshot_blob_references` migration,
+  # `SnapshotBlobReference.table_exists?` is false and the exclusion subquery short-circuits —
+  # the job then behaves identically to Rails' built-in unattached-blob cleanup, just delayed
+  # by `Glib::PurgeUnattached::Config.min_age` (8 hours by default) to give upload flows time
+  # to attach.
+  #
+  # Schedule from the host app (e.g. via sidekiq-cron):
+  #   Glib::PurgeUnattachedJob.perform_later
+  #
+  # Adjust the grace window from the host app (e.g. for a slower upload flow):
+  #   Glib::PurgeUnattached::Config.min_age = 10.hours
+  class PurgeUnattachedJob < ApplicationJob
+    queue_as :cleanup
+
+    def perform(*_args)
+      scope = ActiveStorage::Blob
+        .unattached
+        .where('active_storage_blobs.created_at < ?', Glib::PurgeUnattached::Config.min_age.ago)
+
+      if SnapshotBlobReference.table_exists?
+        scope = scope.where.not(id: SnapshotBlobReference.select(:blob_id))
+      end
+
+      scope.find_each(&:purge_later)
+    end
+  end
+end