gemstack 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3653be40ea53434b0176c572f0ecdba840c2af0b639a7d4ed64a9117037c72f4
-  data.tar.gz: 2a6fe58ab592b81ee4ecd2bbe794a9e6e94f1b693afa6963725f6ac1a0719f93
+  metadata.gz: 6b4da4865f171f049ffb5861de51b0f9e376e8e684dac8c897c760194b1269ad
+  data.tar.gz: 678190d65346a0542c88f0e977227c477666d98c92bf252eb5d03cae23116796
 SHA512:
-  metadata.gz: f0059eae0a47937b5984e631adfd2430e0b261845f4d6165f3288d269b63cd3d9601b89b4b0efbde33933e678128350c4bdab767ed7cf8927d0e2272691beaee
-  data.tar.gz: 169b95e87f103a9d21a07e60b51da63da756381bdc541d9e57abf0224454e364d4d1d64c931398f3f702b545f4f5463be30eeefe7468ec899651ac1c63c04d8d
+  metadata.gz: 6d16bf203a45f8b40a37dd13cac7d31c983b5f71ea84c6ae90d5dc566f306b650b6ab3410edcfe1c21248f0accf3af9870db4f57567727a0395678beb65d6897
+  data.tar.gz: 392c2b983fb86297436e835136c92fc37c19fe6649bb55b3ea5c7f9d0e058849e397634ebcd612806d264f27edaced07ed55689c4b1504e28d0abcfe5ed8c531

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.4.0
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.3.6
 
 See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,9 +1,9 @@
 # gemstack
 
-GemStack: a fast, modular Ruby API framework for Next.js applications.
+GemStack: a fast, modular Ruby web application framework with a Next.js frontend.
 
-Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby web application framework with
+a Next.js frontend, by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed
 together in that repository and released with the same version.
 
 ## Installation

data/lib/gemstack/application.rb

@@ -99,6 +99,10 @@ module GemStack
       (app_dirs + extra).select { |path| File.directory?(path) }
     end
 
+    # Held shared while application code runs (requests, realtime handlers),
+    # exclusively while code reloads.
+    def interlock = @interlock ||= Interlock.new
+
     private
 
     def load_env_files = GemStack.load_env_files!

data/lib/gemstack/cli/app_generator.rb

@@ -66,6 +66,9 @@ module GemStack
             (!frontend? && %w[dot_node-version.tt dot_nvmrc.tt].include?(rel))
         })
         render_directory("frontend", File.join(destination, "frontend")) if frontend?
+        # Background jobs work from the start: the jobs table is part of every app
+        # with a database, so `gemstack dev` runs a worker right away.
+        JobGenerator.install_migration(destination, output: @output, timestamp: @options[:jobs_timestamp]) if database?
         install unless @options[:skip_install]
         git_init unless @options[:skip_git]
         summary
@@ -100,13 +103,15 @@ module GemStack
       end
 
       # Best effort: a missing or password-protected database server shouldn't fail `new`.
+      # Migrating creates the jobs table, so the dev worker can start at once.
       def create_database
-        @output.puts("  #{"run".rjust(9)}  gemstack db:create")
-        ok = unbundled { system("bin/gemstack", "db:create", chdir: destination, out: File::NULL, err: File::NULL) }
+        @output.puts("  #{"run".rjust(9)}  gemstack db:create db:migrate")
+        quiet = { chdir: destination, out: File::NULL, err: File::NULL }
+        ok = unbundled { system("bin/gemstack", "db:create", **quiet) && system("bin/gemstack", "db:migrate", **quiet) }
         return if ok
 
-        @output.puts("  #{"warning".rjust(9)}  couldn't create the database — " \
-                     "check config/database.yml (or set DATABASE_URL in .env), then run `gemstack db:create`")
+        @output.puts("  #{"warning".rjust(9)}  couldn't create or migrate the database — check config/database.yml " \
+                     "(or set DATABASE_URL in .env), then run `gemstack db:create db:migrate`")
       end
 
       def git_init

data/lib/gemstack/cli/doctor.rb

@@ -219,7 +219,8 @@ module GemStack
                   "set DATABASE_URL, or a production section in config/database.yml")
         elsif settings[:adapter] == "sqlite"
           caution("SQLite in production (#{settings[:database]})",
-                  "keep the file on a persistent volume and run a single server; back it up")
+                  "PostgreSQL is recommended: add gem \"pg\" and set DATABASE_URL=postgres://… — SQLite only " \
+                  "suits one server, with the file on a persistent volume and backups")
         else
           pass("production database: #{GemStack::DB::Configuration.describe(settings)} (#{settings[:source]})")
         end

data/lib/gemstack/cli/migration_changes.rb

@@ -133,8 +133,9 @@ module GemStack
       end
 
       def field_argument(field)
-        [field.name, field.type, ("optional" if field.optional), ("unique" if field.unique),
-         ("index" if field.index && !field.reference?)].compact.join(":")
+        modifiers = { "optional" => field.optional, "unique" => field.unique,
+                      "index" => field.index && !field.reference? }.select { |_, on| on }.keys
+        [field.name, field.type, field.enum_values&.join(","), *modifiers].compact.join(":")
       end
 
       def manual_review

data/lib/gemstack/cli/resource_generator.rb

@@ -63,6 +63,9 @@ module GemStack
         when "references"
           "foreign_key :#{field.column}, :#{field.referenced_table}, type: :Bignum#{null}, on_delete: :restrict"
         when "boolean" then "TrueClass :#{field.name}, null: false, default: false"
+        when "enum"
+          default = field.default_value ? ", null: false, default: #{field.default_value.inspect}" : ""
+          "String :#{field.name}, size: 50#{default}#{", unique: true" if field.unique}"
         else
           unique = field.unique && field.type != "json" ? ", unique: true" : ""
           format(COLUMN_TYPES.fetch(field.type), field.name) + null + unique
@@ -70,6 +73,11 @@ module GemStack
       end
 
       def model_field(field)
+        if field.enum?
+          default = field.default_value ? ", default: #{field.default_value.inspect}" : ", null: true"
+          return "enum :#{field.name}, %w[#{field.enum_values.join(" ")}]#{default}"
+        end
+
         options = []
         options << "null: false" if field.required?
         options << "null: false, default: false" if field.type == "boolean"
@@ -87,6 +95,7 @@ module GemStack
         when "integer", "bigint", "float", "references" then "String(#{attr} ?? \"\")"
         when "datetime" then "(#{attr} ?? \"\").slice(0, 16)"
         when "json" then "#{attr} == null ? \"\" : JSON.stringify(#{attr}, null, 2)"
+        when "enum" then "#{attr} ?? #{field.default_value.to_s.inspect}"
         else "#{attr} ?? \"\""
         end
       end
@@ -94,7 +103,7 @@ module GemStack
       # Expression turning a form value into an API input value.
       def form_output(field)
         value = "values.#{field.column}"
-        return value if field.type == "boolean"
+        return value if field.type == "boolean" || (field.enum? && !field.optional)
 
         converted =
           case field.type
@@ -115,6 +124,10 @@ module GemStack
           %(<input #{common} type="checkbox" checked={values.#{key}} onChange={set("#{key}")} />)
         when "text", "json"
           %(<textarea #{common} rows={4} value={values.#{key}} onChange={set("#{key}")}#{required} />)
+        when "enum"
+          options = field.enum_values.map { |value| %(<option value="#{value}">#{Inflector.humanize(value)}</option>) }
+          options.unshift(%(<option value="">—</option>)) if field.optional
+          %(<select #{common} value={values.#{key}} onChange={set("#{key}")}>#{options.join}</select>)
         else
           attrs = { "integer" => %(type="number" step="1"), "bigint" => %(type="number" step="1"),
                     "references" => %(type="number" step="1"), "float" => %(type="number" step="any"),

data/lib/gemstack/cli/resource_spec.rb

@@ -6,18 +6,23 @@ module GemStack
     # resource, parsed once from the command line (ARCHITECTURE §7):
     #
     #   gemstack generate resource Product name:string price:decimal description:text:optional \
-    #                                      sku:string:unique category:references active:boolean
+    #                                      sku:string:unique category:references active:boolean \
+    #                                      status:enum:draft,published,archived
     #
-    # Field syntax: name:type[:modifier...]. Fields are required (NOT NULL)
-    # unless marked :optional. Booleans default to false. Modifiers: optional,
-    # unique, index.
+    # Field syntax: name:type[:modifier...]; enums list their values first
+    # (name:enum:a,b,c[:modifier...]). Fields are required (NOT NULL) unless
+    # marked :optional. Booleans default to false, enums to their first value.
+    # Modifiers: optional, unique, index.
     class ResourceSpec
-      TYPES = %w[string text integer bigint float decimal boolean date datetime uuid json references].freeze
+      TYPES = %w[string text integer bigint float decimal boolean date datetime uuid json references enum].freeze
       MODIFIERS = %w[optional unique index].freeze
       REST_ACTIONS = %w[index show create update destroy].freeze
 
-      Field = Struct.new(:name, :type, :optional, :unique, :index, keyword_init: true) do
-        def required? = !optional && type != "boolean"
+      Field = Struct.new(:name, :type, :optional, :unique, :index, :enum_values, keyword_init: true) do
+        # Booleans and enums are NOT NULL too, but with a default: nothing to require.
+        def required? = !optional && !%w[boolean enum].include?(type)
+        def enum? = type == "enum"
+        def default_value = enum? && !optional ? enum_values.first : nil
         def reference? = type == "references"
         def column = reference? ? "#{name}_id" : name
         def label = Inflector.humanize(name)
@@ -78,12 +83,24 @@ module GemStack
                 "Unknown type #{type.inspect} in #{arg.inspect}; types: #{TYPES.join(", ")}"
         end
 
+        enum_values = parse_enum_values(arg, mods) if type == "enum"
         unknown = mods - MODIFIERS
         raise Thor::Error, "Unknown modifier(s) #{unknown.join(", ")} in #{arg.inspect}" unless unknown.empty?
 
         name = name.delete_suffix("_id") if type == "references"
         Field.new(name: name, type: type, optional: mods.include?("optional"), unique: mods.include?("unique"),
-                  index: mods.include?("index") || type == "references")
+                  index: mods.include?("index") || type == "references", enum_values: enum_values)
+      end
+
+      # status:enum:draft,published → ["draft", "published"] (taken off mods).
+      def parse_enum_values(arg, mods)
+        values = mods.shift.to_s.split(",").map(&:strip)
+        if values.empty? || values.any? { |value| !value.match?(/\A[a-z][a-z0-9_]*\z/) } || values.uniq != values
+          raise Thor::Error, "Give an enum's values in #{arg.inspect}, e.g. status:enum:draft,published " \
+                             "(lowercase letters, digits and _, no duplicates)"
+        end
+
+        values
       end
 
       def lower_camel(term)

data/lib/gemstack/cli/template_update.rb

@@ -84,7 +84,8 @@ module GemStack
     # templates (offline), files that differ are offered, never updated.
     class TemplateUpdate
       VERSION_FILE = ".gemstack/version"
-      # Managed elsewhere: the Gemfile by `gemstack update`/Bundler.
+      # Managed elsewhere: the Gemfile by `gemstack update`/Bundler. Migrations
+      # (db/migrations/) are the app's history and never part of an update.
       MANAGED = %w[Gemfile .gemstack/version].freeze
 
       # created/updated/saved (as FILE.new) are done; conflicts were left for you;
@@ -171,7 +172,7 @@ module GemStack
           AppGenerator.new(destination, options, output: StringIO.new).run
           Dir.glob("**/*", File::FNM_DOTMATCH, base: destination).sort.filter_map do |rel|
             full = File.join(destination, rel)
-            next unless File.file?(full) && !MANAGED.include?(rel)
+            next unless File.file?(full) && !MANAGED.include?(rel) && !rel.start_with?("db/migrations/")
 
             [rel, AppFile.new(File.binread(full), File.stat(full).mode)]
           end.to_h

data/lib/gemstack/cli.rb

@@ -241,7 +241,7 @@ module GemStack
       are updated, and for ones you edited you choose: overwrite, skip, see the diff, or FILE.new.
 
         gemstack update                       # the latest release
-        gemstack update 0.3.6                 # a specific version
+        gemstack update 0.4.0                 # a specific version
         gemstack update --templates --dry-run # only the template step, preview
         gemstack update --templates --from 0.3.5
     DESC

data/lib/gemstack/contract/builder.rb

@@ -138,13 +138,22 @@ module GemStack
             if attr[:type] == :json && !serializer.attributes_list[attr[:name]].type
               @warnings << "#{serializer.name}##{attr[:name]}: type unknown, emitted as unknown"
             end
-            { name: attr[:name].to_s, type: type_ref(attr[:type]), nullable: attr[:nullable], optional: false }
+            type = enum_values(serializer, attr)&.then { |values| { enum: values } } || type_ref(attr[:type])
+            { name: attr[:name].to_s, type: type, nullable: attr[:nullable], optional: false }
           end
           @types[name] = { fields: fields }
         end
         { ref: name }
       end
 
+      # An inferred string attribute backed by a model enum is a union type.
+      def enum_values(serializer, attr)
+        return nil unless attr[:type] == :string && serializer.attributes_list[attr[:name]]&.type.nil?
+
+        field = serializer.model&.gemstack_fields&.[](attr[:name])
+        field && field.options[:enum]
+      end
+
       def schema_ref(schema, fallback_name)
         name = schema.type_name || fallback_name
         @types[name] ||= { fields: schema_fields(schema) }
@@ -153,7 +162,10 @@ module GemStack
 
       def schema_fields(schema)
         schema.fields.values.map do |field|
-          type = field.schema ? { object: schema_fields(field.schema) } : { scalar: field.type }
+          type = if field.schema then { object: schema_fields(field.schema) }
+                 elsif field.rules[:enum] then { enum: field.rules[:enum].map(&:to_s) }
+                 else { scalar: field.type }
+                 end
           type = { array: type } if field.array
           { name: field.name.to_s, type: type, nullable: field.nullable, optional: field.ts_optional? }
         end

data/lib/gemstack/contract/openapi.rb

@@ -99,6 +99,7 @@ module GemStack
       def schema_for(ref)
         if ref[:scalar] then Types.fetch(ref[:scalar]).openapi.dup
         elsif ref[:ref] then { "$ref": "#/components/schemas/#{ref[:ref]}" }
+        elsif ref[:enum] then { type: "string", enum: ref[:enum] }
         elsif ref[:array] then { type: "array", items: schema_for(ref[:array]) }
         elsif ref[:page] then page_schema(ref[:page])
         elsif ref[:object] then object_schema(ref[:object])

data/lib/gemstack/contract/typescript.rb

@@ -73,6 +73,7 @@ module GemStack
       def ts_type(ref, depth = 0)
         if ref[:scalar] then Types.fetch(ref[:scalar]).ts
         elsif ref[:ref] then ref[:ref]
+        elsif ref[:enum] then ref[:enum].map { |value| JSON.generate(value) }.join(" | ")
         elsif ref[:array]
           inner = ts_type(ref[:array], depth)
           inner.match?(/\A[\w.]+\z/) ? "#{inner}[]" : "Array<#{inner}>"

data/lib/gemstack/db/model.rb

@@ -8,6 +8,8 @@ module GemStack
   #     field :price, :decimal, null: false, gt: 0
   #     field :active, :boolean, null: false, default: true
   #
+  #     enum :status, %w[draft published archived], default: "draft"
+  #
   #     validates :name, format: /\A\S/
   #     belongs_to :category
   #     has_many :reviews
@@ -26,7 +28,7 @@ module GemStack
   class Model
     Field = Struct.new(:name, :type, :options)
 
-    FIELD_RULES = %i[null default size gt gte lt lte in format].freeze
+    FIELD_RULES = %i[null default size gt gte lt lte in enum format].freeze
 
     plugin :timestamps, update_on_create: true
     plugin :validation_helpers
@@ -46,7 +48,8 @@ module GemStack
       end
 
       # Declares a field. Options: null: false (required), default:, size:
-      # (max length), gt/gte/lt/lte, in:, format:. Types are GemStack::Types.
+      # (max length), gt/gte/lt/lte, in:, enum: (like in:, and a union type
+      # in TypeScript), format:. Types are GemStack::Types.
       def field(name, type, **options)
         Types.fetch(type)
         unknown = options.keys - FIELD_RULES
@@ -58,6 +61,41 @@ module GemStack
                                                  options.freeze)
       end
 
+      def gemstack_enums
+        @gemstack_enums ||= superclass.respond_to?(:gemstack_enums) ? superclass.gemstack_enums.dup : {}
+      end
+
+      # A string column limited to a list of values:
+      #
+      #   enum :status, %w[draft published archived], default: "draft"
+      #
+      # It is validated, the request schema accepts only those values,
+      # TypeScript gets "draft" | "published" | "archived", and it adds
+      #
+      #   Post.statuses           # => ["draft", "published", "archived"]
+      #   post.published?         # status == "published"
+      #   post.published!         # update(status: "published")
+      #   Post.published          # where(status: "published"), chainable
+      #
+      # New records start at `default:`. Without one the value is required,
+      # unless null: true. When a helper would clash with another method,
+      # prefix: true names them status_published? etc. (prefix: "is" →
+      # is_published?); scopes: false skips the datasets.
+      def enum(name, values, default: nil, null: false, prefix: nil, scopes: true)
+        name = name.to_sym
+        values = Array(values).map(&:to_s).uniq.freeze
+        raise ArgumentError, "enum #{name}: give at least one value" if values.empty?
+
+        default = default&.to_s
+        if default && !values.include?(default)
+          raise ArgumentError, "enum #{name}: the default #{default.inspect} isn't one of #{values.inspect}"
+        end
+
+        field(name, :string, null: null, enum: values, **(default ? { default: default } : {}))
+        gemstack_enums[name] = Enum.new(name, values, default)
+        define_enum_helpers(name, values, prefix, scopes)
+      end
+
       def gemstack_validations
         @gemstack_validations ||=
           superclass.respond_to?(:gemstack_validations) ? superclass.gemstack_validations.dup : []
@@ -104,6 +142,38 @@ module GemStack
 
       private
 
+      def define_enum_helpers(name, values, prefix, scopes)
+        prefix = { true => "#{name}_", nil => "", false => "" }.fetch(prefix) { "#{prefix}_" }
+        enum_method(name, Inflector.pluralize(name.to_s), singleton: true) { values }
+        values.each do |value|
+          method = "#{prefix}#{value.gsub(/\W+/, "_")}"
+          unless method.match?(/\A[a-z_][A-Za-z0-9_]*\z/)
+            raise ArgumentError, "enum #{name}: #{value.inspect} can't be a method name; use prefix:"
+          end
+
+          enum_method(name, "#{method}?") { self[name] == value }
+          enum_method(name, "#{method}!") { update(name => value) }
+          enum_method(name, method, singleton: true) { where(name => value) } if scopes
+        end
+      end
+
+      # Defines one helper, refusing to replace an existing method (e.g. a
+      # value "new" would replace Model.new: use prefix:).
+      def enum_method(name, method, singleton: false, &body)
+        taken = singleton ? respond_to?(method, true) : method_defined?(method) || private_method_defined?(method)
+        if taken
+          raise ArgumentError, "enum #{name}: #{singleton ? "#{self}." : "#"}#{method} already exists; " \
+                               "use prefix: true (or prefix: \"…\")"
+        end
+
+        if singleton
+          define_singleton_method(method, &body)
+          dataset_module { define_method(method, &body) } unless method == Inflector.pluralize(name.to_s)
+        else
+          define_method(method, &body)
+        end
+      end
+
       # PostgreSQL's jsonb comes back as Hash/Array (pg_json); MySQL JSON and
       # SQLite text come back as strings, so those fields are (de)serialized.
       def serialize_json(name)
@@ -144,6 +214,8 @@ module GemStack
       end
     end
 
+    Enum = Data.define(:name, :values, :default)
+
     alias update! update
 
     # Identifies this version of the record, for ETags (Controller#stale?) and
@@ -171,6 +243,14 @@ module GemStack
 
     private
 
+    # New records start at their enums' defaults.
+    def initialize_set(values)
+      super
+      self.class.gemstack_enums.each_value do |enum|
+        @values[enum.name] = enum.default if enum.default && !@values.key?(enum.name)
+      end
+    end
+
     def validate_fields
       self.class.gemstack_fields.each_value do |field|
         opts = field.options
@@ -197,9 +277,9 @@ module GemStack
         words = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
         validates_operator(operator, opts[key], name, message: "must be #{words[key]} #{opts[key]}", allow_nil: true)
       end
-      if opts[:in]
-        validates_includes(opts[:in], name, message: "must be one of: #{opts[:in].to_a.join(", ")}",
-                                            allow_nil: true)
+      allowed = opts[:enum] || opts[:in]
+      if allowed
+        validates_includes(allowed, name, message: "must be one of: #{allowed.to_a.join(", ")}", allow_nil: true)
       end
       validates_format(opts[:format], name, message: "is invalid", allow_nil: true) if opts[:format]
     end

data/lib/gemstack/db/testing.rb

@@ -47,7 +47,8 @@ module GemStack
 
       def sample_value(model, field, sequence)
         opts = field.options
-        return Array(opts[:in]).first if opts[:in]
+        allowed = opts.values_at(:enum, :in).compact.first
+        return Array(allowed).first if allowed
 
         case field.type
         when :string, :text then sample_string(field, opts, sequence)

data/lib/gemstack/errors.rb

@@ -83,8 +83,18 @@ module GemStack
   class ValidationError < Error
     status 422, "validation_failed", "Validation failed"
 
+    # Without a message, it lists the errors — "Validation failed: name is
+    # required, price must be greater than 0" — so logs, consoles and clients
+    # that only show the message say what failed.
     def initialize(message = nil, errors: {}, **)
-      super(message, details: errors, **)
+      super(message || self.class.summary(errors), details: errors, **)
+    end
+
+    def self.summary(errors)
+      list = errors.to_h.flat_map do |field, messages|
+        Array(messages).map { |text| %w[base _base].include?(field.to_s) ? text : "#{field} #{text}" }
+      end
+      list.empty? ? default_message : "#{default_message}: #{list.join(", ")}"
     end
 
     def errors = details

data/lib/gemstack/interlock.rb

@@ -28,6 +28,14 @@ module GemStack
       end
     end
 
+    # Runs application code outside a request (e.g. realtime handlers).
+    def shared
+      acquire_shared
+      yield
+    ensure
+      release_shared
+    end
+
     def exclusive
       @mutex.synchronize do
         @waiting_writers += 1

data/lib/gemstack/reloader.rb

@@ -14,7 +14,7 @@ module GemStack
       @app = app
       @application = application
       @watcher = Dev::FileWatcher.new(WATCHED, root: application.root)
-      @interlock = Interlock.new
+      @interlock = application.interlock
       @check = Mutex.new
     end
 

data/lib/gemstack/schema.rb

@@ -10,6 +10,7 @@ module GemStack
   #     required :name, :string, max_length: 120
   #     required :price, :decimal, gt: 0
   #     optional :active, :boolean, default: true
+  #     optional :status, :string, enum: %w[draft published]   # "draft" | "published" in TypeScript
   #     optional :tags, [:string]
   #     optional :dimensions do
   #       required :width, :integer
@@ -33,7 +34,7 @@ module GemStack
     end
 
     NO_DEFAULT = Object.new.freeze
-    RULES = %i[gt gte lt lte min_length max_length in format].freeze
+    RULES = %i[gt gte lt lte min_length max_length in enum format].freeze
     STRING_TYPES = %i[string text].freeze
 
     # rule => [passes?(value, arg), message(arg)]
@@ -45,6 +46,7 @@ module GemStack
       min_length: [->(v, a) { v.to_s.length >= a }, ->(a) { "is too short (minimum #{a} characters)" }],
       max_length: [->(v, a) { v.to_s.length <= a }, ->(a) { "is too long (maximum #{a} characters)" }],
       in: [->(v, a) { a.include?(v) }, ->(a) { "must be one of: #{a.to_a.join(", ")}" }],
+      enum: [->(v, a) { a.include?(v) }, ->(a) { "must be one of: #{a.to_a.join(", ")}" }], # + a TS union
       format: [->(v, a) { a.match?(v.to_s) }, ->(_) { "is invalid" }]
     }.freeze
 

data/lib/gemstack/version.rb

@@ -2,5 +2,5 @@
 
 module GemStack
   # All GemStack gems are released together under a single version.
-  VERSION = "0.3.6"
+  VERSION = "0.4.0"
 end

data/templates/app/Gemfile.tt

@@ -14,9 +14,9 @@ gem "puma", ">= 6.4"
 <% if database? -%>
 gem "<%= driver_gem %>", "<%= driver_version %>" # the <%= database_adapter %> driver (config/database.yml)
 <% end -%>
+gem "brotli", "~> 0.8" # Brotli response compression for browsers that accept it (gzip otherwise)
 
 # Any gem works here as usual, e.g.:
-# gem "brotli"         # Brotli compression (gzip is used without it)
 # gem "redis-client"   # shared cache: config.cache.store = :redis
 # gem "stripe"
 

data/templates/app/config/app.rb.tt

@@ -34,7 +34,8 @@ GemStack.configure do |config|
   # config.http.pagination.max_per_page = 100      # the most a client may ask for with ?per_page=
 
   # ── Responses ───────────────────────────────────────────────────────────
-  # config.http.compression.enabled = true         # gzip/Brotli responses over 1 KB (add gem "brotli" for br)
+  # config.http.compression.enabled = true         # Brotli/gzip by Accept-Encoding, for text/JSON over 1 KB
+  # config.http.compression.encodings = %w[br gzip] # preference order; Brotli uses the brotli gem
   # config.http.etags = true                       # ETag + 304 Not Modified for GET responses
 
   # ── Logging ─────────────────────────────────────────────────────────────

data/templates/app/config/database.yml.tt

@@ -15,7 +15,10 @@ test:
   <<: *default
   database: db/test.sqlite3
 
-# Keep the file on persistent storage (a volume); or set DATABASE_URL=sqlite3:/data/app.sqlite3.
+# Production: use PostgreSQL. Add gem "pg" and set
+#   DATABASE_URL=postgres://user:password@host:5432/<%= database_name %>_production
+# which overrides this section (hosting platforms set it for you). SQLite below
+# suits a single server only: keep the file on a persistent volume and back it up.
 production:
   <<: *default
   database: db/production.sqlite3

data/templates/deploy/config/deploy.yml.tt

@@ -103,6 +103,8 @@ env:
 <% if sqlite? -%>
 
 # The SQLite file lives on this volume, shared by every role: keep them on one server.
+# For production, PostgreSQL is recommended (docs/database.md): switch the app to it
+# and `gemstack generate deploy --force` adds the database accessory.
 volumes:
   - "<%= service %>_data:/data"
 <% end -%>

data/templates/realtime/config/channels.rb

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
-# Realtime channels browsers may subscribe to (docs/realtime.md). Anything not
-# listed here is refused. `*` matches one segment and is passed to the block,
-# together with the request (cookies, headers) for authorization.
+# What browsers may do over realtime connections (docs/realtime.md).
+# Anything not listed here is refused. `*` matches one segment and is passed
+# to the block, together with the connection's request (cookies, headers).
 #
-#   GemStack.broadcast("orders:#{order.id}", "order.updated", order)
+#   GemStack.broadcast("orders:#{order.id}", "order.updated", order)   # server → browsers
 #
 GemStack.channels do
+  # Who is connecting, once per connection (nil: anonymous). A Hash with an
+  # :id is also the presence metadata others see. With `gemstack add auth`:
+  #   identify { |request| GemStack::Auth.user_from(request)&.then { |u| { id: u.id, name: u.name } } }
+
   # channel "announcements"                        # public
   # channel "orders:*" do |order_id, request|      # private
-  #   Order.find_by(id: order_id)&.user_id == current_user_id(request)
+  #   Order.find_by(id: order_id)&.user_id == identity(request)&.fetch(:id)
+  # end
+  # channel "rooms:*", presence: true do |room_id, request|   # + who's here (usePresence)
+  #   !identity(request).nil?
+  # end
+
+  # Messages browsers send with realtime.send(channel, event, data) — only to
+  # channels they're subscribed to. The return value is the reply.
+  # receive "rooms:*" do |message|
+  #   post = Post.create!(room_id: message.params.first, body: message.data["body"], user_id: message.identity[:id])
+  #   GemStack.broadcast(message.channel, "post.created", post)
+  #   { id: post.id }
   # end
 end