belt 0.6.7 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef904a59417a3f019eab7e6339fc6d13290bf05ff3d1d435c434834cea189bc2
-  data.tar.gz: 93a8820ef48b523d41e7a4aa8d0544090b2472bc7805b96bfee9f0f45c8e8114
+  metadata.gz: 5c8fdcdc85f77c9538860db16ba868045f1a4482487ce7cfbf6b3e1921e9c793
+  data.tar.gz: 996b9b570963202a4b9acde7fdaa4e83550606a7e6ba9ba89cf20dabff1c5cf7
 SHA512:
-  metadata.gz: b562534dbed0dcad13db7d4e6f0ff9ff99f469af4de025a682902375d39ffe0bf73447a749674443acb81632e40f2f2c4b0e34ceced872a37d4a904dd5725b7f
-  data.tar.gz: d0915177422b65ef6f9a2dfb542cdd63b578acdbae1abf97cc4699354400b046e507818f71f7756a73f54183916921d2ad6862c877c4b8385fc6feb22ebd7b2d
+  metadata.gz: 3dbbf13ab635583594d630355888e2197f8a07052348eee39f47a1c328fba39392df21c88f12a8ab34252de920ecf711ba1915785de606a527afc79299ed69e8
+  data.tar.gz: e2f3a01545969526003d72e5c0b486e412c852ef8f6cdd6220ad92be5c6771dba8e0e3f5a1880ed691c72ad9e27a5e0caf11a2916717fcdf74c6e81fe05e871b

data/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## Unreleased
+## 0.6.8
+
+### Added
+
+- **`ttl_attribute` model macro.** `ttl_attribute :expires_at` on a model makes
+  `belt setup tables` emit `ttl { attribute_name = "expiresAt", enabled = true }`
+  for its table. A string is used verbatim. `belt explain models`. (Fizzy #1796)
+
+### Fixed
+
+- **`belt setup tables` no longer silently drops `ttl` blocks.** A hand-added `ttl`,
+  or any other table block or setting the models don't produce (`stream_enabled`,
+  `server_side_encryption`, …), now counts as dropped infrastructure like a
+  hand-added GSI. Interactive runs prompt, and generator auto-syncs (`belt g policies`
+  and friends) skip the file. Hand-written comments the regen removes are now
+  reported instead of vanishing quietly. (Fizzy #1796)
 
 ## 0.6.7
 

data/lib/belt/cli/tables_command.rb

@@ -9,6 +9,8 @@ module Belt
     class TablesCommand
       MODULE_DIR = 'infrastructure/modules/app'
       MODELS_DIR = 'lambda/models'
+      # Table blocks the drop check compares some other way (see #table_settings).
+      DERIVED_BLOCKS = %w[attribute global_secondary_index].freeze
 
       def self.run(args)
         # Environment argument accepted for backwards compatibility but unused —
@@ -99,7 +101,16 @@ module Belt
         # Deduplicate by index name
         indexes.uniq! { |idx| idx[:name] }
 
-        { name: model_name, indexes: indexes }
+        { name: model_name, indexes: indexes, ttl: extract_ttl_attribute(content) }
+      end
+
+      # `ttl_attribute :expires_at` (Belt::Models::TtlMacro). A symbol is camelCased the
+      # way ActiveItem writes it; a string is the DynamoDB attribute name verbatim.
+      def extract_ttl_attribute(content)
+        match = uncommented(content).match(/^\s*ttl_attribute[\s(]+(?::(\w+)|['"]([^'"]+)['"])/)
+        return nil unless match
+
+        match[1] ? Belt::Inflector.camelize_lower(match[1]) : match[2]
       end
 
       def extract_indexes(content)
@@ -180,6 +191,8 @@ module Belt
         if existing_content
           dropped = detect_dropped_infrastructure(existing_content, new_content)
           return if dropped.any? && !safe_to_overwrite?(dest, dropped)
+
+          warn_dropped_comments(dest, dropped_comments(existing_content, new_content))
         end
 
         File.write(dest, new_content)
@@ -215,11 +228,63 @@ module Belt
           old_gsis = gsi_names(existing_content, label)
           new_gsis = gsi_names(new_content, label)
           dropped.concat((old_gsis - new_gsis).map { |gsi| "GSI \"#{gsi}\" on table \"#{label}\"" })
+          dropped.concat(dropped_table_settings(existing_content, new_content, label))
         end
 
         dropped
       end
 
+      # Nested blocks (`ttl`, `server_side_encryption`, …) and settings (`stream_enabled`,
+      # …) a table has today that the regenerated table wouldn't. A hand-added ttl block
+      # is the usual one — dropping it turns expiry off and rows quietly pile up.
+      def dropped_table_settings(existing_content, new_content, label)
+        old_settings = table_settings(table_block(existing_content, label))
+        new_settings = table_settings(table_block(new_content, label))
+
+        (old_settings.keys - new_settings.keys).map do |key|
+          "#{old_settings[key]} on table \"#{label}\""
+        end
+      end
+
+      # Map of identity → description for every top-level setting in a table body.
+      # `attribute` and `global_secondary_index` are compared separately (GSIs) or are
+      # derived from them (attributes), so they're left out here.
+      def table_settings(block)
+        return {} unless block
+
+        settings = {}
+        depth = 0
+        block.each_line do |line|
+          code = line.sub(/#.*/, '').strip
+          if depth.zero?
+            if (name = code[/\A(\w+)\s*\{/, 1])
+              settings.merge!(block_setting(name, block, line)) unless DERIVED_BLOCKS.include?(name)
+            elsif (name = code[/\A(\w+)\s*=/, 1])
+              settings[name] = "setting \"#{name}\""
+            end
+          end
+          depth += code.count('{') - code.count('}')
+        end
+        settings
+      end
+
+      def block_setting(name, block, line)
+        return { name => "block \"#{name}\"" } unless name == 'ttl'
+
+        body = block[block.index(line)..][/\{(.*?)\}/m, 1].to_s
+        attr = body[/attribute_name\s*=\s*"([^"]+)"/, 1]
+        { "ttl:#{attr}" => "ttl on \"#{attr}\"" }
+      end
+
+      # Hand-written comments can't be re-derived either. They're not infrastructure,
+      # so losing them doesn't block the write, but it shouldn't happen silently.
+      def dropped_comments(existing_content, new_content)
+        # The leading banner is Belt's own and changes between versions — skip it.
+        body = existing_content.lines.drop_while { |l| l.strip.empty? || l.lstrip.start_with?('#') }
+        body.map(&:strip).select { |l| l.start_with?('#', '//') } -
+          new_content.lines.map(&:strip)
+      end
+
       # Resource labels for every aws_dynamodb_table block in the content.
       def table_labels(content)
         content.scan(/resource\s+"aws_dynamodb_table"\s+"([^"]+)"/).flatten
@@ -280,19 +345,28 @@ module Belt
       def warn_dropped(dest, dropped)
         puts "\n⚠ Regenerating #{dest} would DROP infrastructure not derived from your models:"
         dropped.each { |d| puts "    • #{d}" }
-        puts "\n  This usually means a table or GSI was added to dynamodb.tf by hand."
-        puts '  Belt only tracks tables and indexes it can read from lambda/models/*.rb,'
+        puts "\n  This usually means a table, GSI, or setting (e.g. ttl) was added to dynamodb.tf by hand."
+        puts '  Belt only tracks what it can read from lambda/models/*.rb (indexes, belongs_to,'
+        puts '  cognito_authenticatable, ttl_attribute),'
         puts '  so a hand-added definition is invisible to the generator and gets overwritten.'
       end
 
+      def warn_dropped_comments(dest, comments)
+        return if comments.empty?
+
+        puts "  ⚠ #{dest}: removed #{comments.size} hand-written comment line(s) " \
+             '(the file is regenerated — put notes on the model instead)'
+      end
+
       def render_dynamodb(models)
         blocks = models.map { |m| render_table(m) }
         "# Auto-generated by Belt from model definitions in lambda/models/*.rb\n" \
           "#\n" \
           "# Do NOT edit manually. `belt setup tables` overwrites this whole file from\n" \
           "# your models. Any table or GSI added here by hand (that a model doesn't\n" \
-          "# declare) will be DROPPED on the next regeneration. Define indexes on the\n" \
-          "# model via indexes(), belongs_to, or cognito_authenticatable instead.\n\n#{blocks.join("\n\n")}\n"
+          "# declare) will be DROPPED on the next regeneration, as will ttl blocks and\n" \
+          "# comments. Define indexes on the model via indexes(), belongs_to, or\n" \
+          "# cognito_authenticatable, and TTL via ttl_attribute, instead.\n\n#{blocks.join("\n\n")}\n"
       end
 
       def render_table(model)
@@ -360,6 +434,14 @@ module Belt
           lines << '  }'
         end
 
+        if model[:ttl]
+          lines << ''
+          lines << '  ttl {'
+          lines << "    attribute_name = \"#{model[:ttl]}\""
+          lines << '    enabled        = true'
+          lines << '  }'
+        end
+
         lines << ''
         lines << '  point_in_time_recovery {'
         lines << '    enabled = var.enable_pitr'

data/lib/belt/docs/models.md

@@ -144,6 +144,26 @@ ActiveItem::Transaction.write do |tx|
 end
 ```
 
+## Time To Live (TTL)
+
+Let DynamoDB expire rows by declaring the TTL attribute on the model:
+
+```ruby
+class Session < ApplicationRecord
+  ttl_attribute :expires_at   # stored as expiresAt; must hold epoch seconds
+end
+```
+
+`belt setup tables` emits the matching `ttl { attribute_name = "expiresAt" }` block in
+`dynamodb.tf`. A symbol is camelCased the way ActiveItem writes it; pass a string
+(`ttl_attribute 'expires_at_epoch'`) to use the DynamoDB attribute name as-is.
+
+Don't add `ttl` (or any other block) to `dynamodb.tf` by hand. The generator overwrites
+the whole file from your models. If a regeneration would drop a hand-added table, GSI,
+`ttl` or other table setting, `belt setup tables` asks before overwriting, and a
+generator's auto-sync skips the file. Comments in the file are lost too (Belt prints a
+warning), so put notes on the model.
+
 ## Generating Models
 
 ```bash

data/lib/belt/models/ttl_macro.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'activeitem'
+require_relative '../inflector'
+
+module Belt
+  module Models
+    # Declares the DynamoDB Time To Live attribute for a model's table:
+    #
+    #   class Session < ApplicationRecord
+    #     ttl_attribute :expires_at   # → ttl { attribute_name = "expiresAt" }
+    #   end
+    #
+    # DynamoDB does the expiring, so at runtime this only records the name. The point
+    # is that `belt setup tables` reads it and emits the `ttl { }` block — a block
+    # added straight into dynamodb.tf would be dropped by the next regeneration.
+    #
+    # A symbol is camelCased the way ActiveItem stores it (`:expires_at` → `expiresAt`).
+    # Pass a string to use the DynamoDB attribute name verbatim (e.g. when the model
+    # remaps it with dynamo_attribute_map).
+    module TtlMacro
+      def ttl_attribute(name = nil)
+        return @ttl_attribute if name.nil?
+
+        @ttl_attribute = name.is_a?(Symbol) ? Belt::Inflector.camelize_lower(name.to_s) : name.to_s
+      end
+    end
+  end
+end
+
+ActiveItem::Base.extend(Belt::Models::TtlMacro)

data/lib/belt/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.7'
+  VERSION = '0.6.8'
 
   # Ruby version new apps run on in Lambda. Rendered into the conveyor-belt
   # provider block (`ruby_version`) by `belt new` / `belt generate environment`.

data/lib/belt.rb

@@ -55,5 +55,6 @@ module Belt
 end
 
 require_relative 'belt/authentication'
+require_relative 'belt/models/ttl_macro'
 require_relative 'belt_controller/base'
 require_relative 'belt/controllers/welcome_controller'

data/lib/templates/new_app/AGENTS.md.erb

@@ -57,6 +57,11 @@ belt apply <env>
 
 This creates: model, controller (with all CRUD actions), route entry, and DynamoDB schema.
 
+`infrastructure/modules/app/dynamodb.tf` is generated. Declare everything on the model:
+GSIs via `indexes(...)` / `belongs_to`, TTL via `ttl_attribute :expires_at`. Anything
+you add to the `.tf` by hand (a `ttl` block, a comment) gets dropped the next time it's
+regenerated.
+
 ### Add a model only (no API endpoint)
 
 ```bash

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.6.7
+  version: 0.6.8
 platform: ruby
 authors:
 - Stowzilla
@@ -186,6 +186,7 @@ files:
 - lib/belt/inflector.rb
 - lib/belt/lambda_handler.rb
 - lib/belt/migration.rb
+- lib/belt/models/ttl_macro.rb
 - lib/belt/observability.rb
 - lib/belt/parameters.rb
 - lib/belt/rendering.rb