omen 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77023f5984f5bf7b9d121db8f2b233f1c69dcb0ae4580f31d78794f3c136c77c
-  data.tar.gz: d2b51269750ab2b89cac43fb90e8382508abc80dd7ed9c4ff2577f65aadeec12
+  metadata.gz: c51ab71a4d3ccce3f1bdcfa1e6f4b6a8196e2778f55368e7dea902e220f367d4
+  data.tar.gz: '003328f8dcba05fe6654e1852b8c9c18ef5e305d8c0ba95456b266c01880c546'
 SHA512:
-  metadata.gz: 16057a3aefe593c75889520a214e3697a61c3c72fd8115374eb62d8236dd51c1123c0169c5ff89ea6b38a1e6d0c262eaef9a9a0bfc9f39870c3d009ccd167bcc
-  data.tar.gz: 9bc6b5f7967966b99b8f666a135fc627d063109f0d228666b221dd4e1f18894554338c455cb56a46a0421c1fc1f2fe6f3d07408e9db614359f97c86f5d7aaeb8
+  metadata.gz: 89a995c7beebd10a587d370ba7e8762f4e92a05252985045666101e64af81f10e5b7100631d670bd12ef89fe527fd4fc744f56918d26500268a39667311ee941
+  data.tar.gz: cf1a91b08d3e40e10d4a43a12872f2befad7cdefea114bbfe0e0e4eb78a8eb55076201ac8bf55e0bd2cd22d9a7ae3a4525367880d0a9622aa05a3d6f11e9062f

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 0.9.0 - 2026-09-18
+
+* [Fix] An answer landing touches the reading it belongs to, so a page watching one refreshes
+  on the answer rather than on whichever status change the run happens to make around it. A
+  question already touched its reading, which is why a question appeared and its answer did not.
+* [Fix] Making an audience's role and letting members into it are two transactions, not one.
+  A managed database refuses to make a role at all, and a refusal takes its whole transaction
+  with it -- so the membership a role already there only needed was rolled back with the
+  refusal, and every statement run as it went on saying the app was misconfigured.
+* [Change] An audience whose Postgres role could not be made says so once and narrows nothing,
+  rather than failing table by table and then reporting the audience narrowed. A managed
+  database refuses `CREATE ROLE` to the app's own user, and the refusal used to arrive as a
+  screenful of `role does not exist` followed by a success line.
+
+## 0.8.0 - 2026-09-16
+
+* [Feature] Make how a Postgres role is made safely public, so a host builds the read-only role
+  Omen requires with the care Omen builds its own: `Omen::Grants.made` takes `login:`,
+  `Omen::Attributes.dangerous` and `.settable` take the role they are about, and `Omen.attempted`
+  and `Omen.each_database` are the two a host's rake task calls. A host had to hand-write all of
+  it, and the copy in Fountain asserted `NOSUPERUSER` -- which only a superuser may say, so the
+  grant died at its second statement, warned, and left the deploy green for a year
+
+* [Breaking change] `Omen::Attributes.exists?`, `.held` and `.dangerous` take the role to ask
+  about rather than reading `Omen.config.narrow_role`, since a host asks about its own
+
+* [Breaking change] `Omen::Attributes::SETTABLE` no longer carries `NOLOGIN`, which is now the
+  default of `Omen::Attributes.settable login:` -- a role a host connects as needs `LOGIN`
+
+* [Breaking change] `Omen::Inquirer.attempted` is `Omen.attempted` and `Omen::Inquirer::REFUSED`
+  is `Omen::REFUSED`. Neither was ever about the inquirer, and a host calling `Omen::Inquirer`
+  to build its reader read as though the two roles were one
+
 ## 0.7.0 - 2026-09-12
 
 * [Bugfix] Keep the columns of an answer in the order the statement asked for them. They were

data/INSTRUCTIONS.md

@@ -104,8 +104,10 @@ end
 - **A read-only connection role.** `connects_to database: { writing: :primary, reading: :reader }`
   on the record class, with the `reading` entry logging in as a Postgres role granted `SELECT`
   and nothing else. Omen raises rather than falling back to a role that could write, which is
-  the point. Creating that role is the app's own business — Omen has no name for it, and
-  discovers it when granting.
+  the point. Naming that role is the app's own business — Omen has none for it, and discovers
+  it when granting — but making one is not, since a managed database refuses half the DDL it
+  takes. `Omen::Grants.made`, `Omen::Attributes.dangerous`, `Omen.attempted` and
+  `Omen.each_database` are public for that, and the README shows the task they add up to.
 - **Active Record Encryption keys.** Without them an encrypted column reads back as the
   placeholder rather than as the value, quietly.
 - **An `ApplicationJob`.** A reading is answered outside the request, and the job descends

data/README.md

@@ -41,6 +41,32 @@ None of it is Omen's to create, and each is checked rather than assumed:
 - **A read-only connection role**: `connects_to database: { writing: :primary, reading: :reader }`
   on `ApplicationRecord`, where `reader` logs in as a Postgres role granted `SELECT` and nothing
   else. Omen raises rather than falling back to a role that could write, which is the point.
+  Naming that role is yours; making one safely is not, since a managed database refuses half the
+  DDL it takes — so `Omen::Grants.made`, `Omen::Attributes.dangerous`, `Omen.attempted` and
+  `Omen.each_database` are public, and a host's own task is the grants it wants and little else:
+
+      module Reader
+        ROLE = 'your_app_reader'
+
+        def self.grant = Omen.each_database { |connection| grant_on connection }
+
+        def self.grant_on(connection)
+          statements(connection).each { |it| Omen.attempted connection, it }
+          held = Omen::Attributes.dangerous connection, ROLE
+          warn "#{ROLE} holds #{held.to_sentence}" if held.any?
+        end
+
+        def self.statements(connection)
+          role = connection.quote_table_name ROLE
+          Omen::Grants.made(connection, ROLE, login: true) +
+            [ "GRANT SELECT ON ALL TABLES IN SCHEMA public TO #{role}", ... ]
+        end
+      end
+
+  `Omen.attempted` runs each statement in a savepoint and warns rather than raising, so one
+  refusal discards neither the deploy nor the statements behind it. `Omen::Grants.made` asserts
+  only what whoever may create a role may set: saying `NOSUPERUSER` needs the `SUPERUSER`
+  attribute, so it is read back with `Omen::Attributes.dangerous` and warned about instead.
 - **`ANTHROPIC_API_KEY`**, or a key named in the initializer.
 - **Active Record Encryption keys**, without which an encrypted column reads back as a
   placeholder rather than as its value, quietly.

data/app/models/omen/answer.rb

@@ -5,7 +5,10 @@ class Omen::Answer < Omen.config.record
   # A \uXXXX escape that outlived JSON.parse, because Claude escaped the backslash of its own.
   UNICODE_ESCAPE = /\\u([0-9a-fA-F]{4})/
 
-  belongs_to :question
+  # Touched, so that a reading whose answer has just landed says so: the reading is what
+  # broadcasts, and the row it broadcasts for is this one. Without it a page waits on the
+  # status the run happens to change around the answer rather than on the answer itself.
+  belongs_to :question, touch: true
 
   # @return [String] the side of the conversation this was said on, in the words the API uses.
   def role = 'assistant'

data/lib/omen/attributes.rb

@@ -1,35 +1,42 @@
 module Omen
-  # What the role a statement runs as may and may not be. A role is created with every dangerous
-  # attribute already off, so this gem sets only what whoever created it may set, and reads the
-  # rest back rather than asserting them: saying `NOSUPERUSER` needs the SUPERUSER attribute, so
-  # a managed database refuses the very statement that would have made the role safe.
+  # What a Postgres role may and may not be. A role is created with every dangerous attribute
+  # already off, so this gem sets only what whoever created it may set, and reads the rest back
+  # rather than asserting them: saying `NOSUPERUSER` needs the SUPERUSER attribute, so a managed
+  # database refuses the very statement that would have made the role safe.
   module Attributes
     # Set on the role, because whoever may create a role may set these.
-    SETTABLE = 'NOLOGIN NOCREATEDB NOCREATEROLE'
+    SETTABLE = 'NOCREATEDB NOCREATEROLE'
 
     # Read back instead, since saying no to one of these needs the attribute itself.
     DANGEROUS = { rolsuper: 'SUPERUSER', rolbypassrls: 'BYPASSRLS',
                   rolreplication: 'REPLICATION', }
 
+    # @param login [Boolean] whether anything connects as the role.
+    # @return [String] what an ALTER ROLE may assert against any database, managed or not.
+    def self.settable(login: false) = "#{login ? 'LOGIN' : 'NOLOGIN'} #{SETTABLE}"
+
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to ask about.
     # @return [Boolean] whether the role is there at all to be granted anything.
-    def self.exists?(connection) = held(connection).present?
+    def self.exists?(connection, name) = held(connection, name).present?
 
     # Nil where there is no such role, so that an empty list and a missing role read apart.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to ask about.
     # @return [Hash, nil] the row of what the role is, or nothing where the role is not.
-    def self.held(connection)
+    def self.held(connection, name)
       connection.select_one <<~SQL.squish
         SELECT #{DANGEROUS.keys.join ', '} FROM pg_roles
-        WHERE rolname = #{connection.quote Omen.config.narrow_role}
+        WHERE rolname = #{connection.quote name}
       SQL
     end
 
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [Array<String>] what the role holds that no reading should be able to reach.
-    def self.dangerous(connection)
-      row = held(connection) || {}
-      DANGEROUS.filter_map { |column, name| name if row[column.to_s] }
+    # @param name [String] the role to ask about.
+    # @return [Array<String>] what the role holds that no read-only request should reach.
+    def self.dangerous(connection, name)
+      row = held(connection, name) || {}
+      DANGEROUS.filter_map { |column, attribute| attribute if row[column.to_s] }
     end
   end
 end

data/lib/omen/grants.rb

@@ -30,8 +30,10 @@ module Omen
       ]
     end
 
-    # The same role, made for one audience rather than for every table: it is granted nothing
-    # here, since a narrowing names the tables and the columns of each itself.
+    # Who may enter the role, and the schema it reads in. Kept apart from making the role: a
+    # managed database refuses to make one at all, and a refusal takes its whole transaction
+    # with it -- so membership granted in the same breath would be lost to a role that was
+    # already there and only needed letting into.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @param name [String] the role to make.
     # @param members [Array<String>] the roles that may enter it, none of them inheriting it.
@@ -39,7 +41,6 @@ module Omen
     def self.narrowed(connection, name, members)
       role = connection.quote_table_name name
       [
-        *made(connection, name),
         *members.map { |member| apart role, connection.quote_table_name(member) },
         "GRANT USAGE ON SCHEMA public TO #{role}",
       ]
@@ -70,12 +71,14 @@ module Omen
 
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @param name [String] the role to make, where the database has not got it.
+    # @param login [Boolean] whether anything connects as it, as a host's reading role does.
     # @return [Array<String>] the statements that make it and say what it may be.
-    def self.made(connection, name)
+    def self.made(connection, name, login: false)
       role = connection.quote_table_name name
+      entered = login ? 'LOGIN' : 'NOLOGIN'
       [ 'DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = ' \
-          "#{connection.quote name}) THEN CREATE ROLE #{role} NOLOGIN; END IF; END $$",
-        "ALTER ROLE #{role} WITH #{Attributes::SETTABLE}", ]
+          "#{connection.quote name}) THEN CREATE ROLE #{role} #{entered}; END IF; END $$",
+        "ALTER ROLE #{role} WITH #{Attributes.settable login: login}", ]
     end
 
     # Intersected, so a bare db:create with no table yet to revoke on is not a failure.

data/lib/omen/inquirer.rb

@@ -14,9 +14,12 @@ module Omen
     UNMADE = 'Could not make %{role}, so every reading will say this app is misconfigured. Ask ' \
              'for that role, NOLOGIN, granted SELECT on every table but %{tables}.'
 
-    # Said per group, since the grants, the revocations and the functions need nothing from one
-    # another and one refusal should not discard the rest.
-    REFUSED = 'Skipped, refused by the database: %{statement} (%{error})'
+    # Said where an audience's own role could not be made. Its tables are then granted to
+    # nobody and no policy stands over them, so every reading of that audience says the app is
+    # misconfigured -- and every statement after the refusal fails for the same reason, which
+    # is one message worth saying and a screenful worth not.
+    UNNARROWED = 'Could not make %{role}, so nothing was narrowed to it and every reading of ' \
+                 'that audience will say this app is misconfigured. Ask for that role, NOLOGIN.'
 
     # Said where a role that already existed is one a reading should not be able to reach through.
     DANGEROUS = '%{role} holds %{held}. This gem cannot take that away without being a superuser ' \
@@ -32,7 +35,7 @@ module Omen
     def self.widen
       Omen.each_database do |connection|
         Omen::Reading.narrowings.each do |narrowing|
-          narrowing.widening(connection).each { |group| attempted connection, *group }
+          narrowing.widening(connection).each { |group| Omen.attempted connection, *group }
           puts "Widened #{connection.current_database} back out of #{narrowing.role}"
         end
       end
@@ -46,12 +49,12 @@ module Omen
       read_by = reader
       warn UNGRANTED % { role: Omen.config.reading_role } unless read_by
       members = [ read_by, connection.select_value(WHOEVER) ].compact
-      Grants.statements(connection, members).each { |statement| attempted connection, statement }
+      Grants.statements(connection, members).each { |it| Omen.attempted connection, it }
       role = Omen.config.narrow_role
       return warn UNMADE % { role: role, tables: Omen.tables.to_sentence } unless
-        Attributes.exists? connection
+        Attributes.exists? connection, role
 
-      held = Attributes.dangerous connection
+      held = Attributes.dangerous connection, role
       warn DANGEROUS % { role: role, held: held.to_sentence } if held.any?
       puts "Granted SELECT on #{connection.current_database} to #{role}"
       narrow connection, members
@@ -62,26 +65,24 @@ module Omen
     # @param members [Array<String>] the roles that may enter a narrowed one.
     # @return [void]
     def self.narrow(connection, members)
-      Omen::Reading.narrowings.each do |narrowing|
-        narrowing.statements(connection, members).each { |group| attempted connection, *group }
-        puts "Narrowed #{narrowing.role} to the rows #{narrowing.setting} names"
-      end
+      Omen::Reading.narrowings.each { |narrowing| narrowed connection, narrowing, members }
     end
 
-    # A group at a time, so a database that refuses one still runs the others -- and each inside
-    # a savepoint of its own, since a refusal inside a transaction refuses everything after it
-    # too, and this task is as likely to be run from a console as from a deploy. What arrives
-    # together is applied together: a table is never left with row level security on and no
-    # policy under it.
+    # One audience: its role made first and asked for straight after, since everything else
+    # here names that role and a database that would not make it refuses the lot. Nothing is
+    # said to have been narrowed where nothing was.
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @param statements [Array<String>] what Omen::Grants or a narrowing built.
+    # @param narrowing [Omen::Narrowing] the audience to write.
+    # @param members [Array<String>] the roles that may enter its role.
     # @return [void]
-    def self.attempted(connection, *statements)
-      connection.transaction(requires_new: true) do
-        statements.each { |statement| connection.execute statement }
-      end
-    rescue ActiveRecord::StatementInvalid => error
-      warn REFUSED % { statement: statements.first.squish, error: error.message.lines.first.strip }
+    def self.narrowed(connection, narrowing, members)
+      making, *holding = narrowing.statements(connection, members)
+      Omen.attempted connection, *making
+      return warn UNNARROWED % { role: narrowing.role } unless
+        Attributes.exists? connection, narrowing.role
+
+      holding.each { |group| Omen.attempted connection, *group }
+      puts "Narrowed #{narrowing.role} to the rows #{narrowing.setting} names"
     end
 
     # Discovered rather than named: SET LOCAL ROLE needs the connecting role to be a member of

data/lib/omen/narrowing.rb

@@ -37,7 +37,8 @@ module Omen
     # @return [Array<Array<String>>] the statements, grouped: what arrives together is applied
     #   together, so no table is left with row level security on and no policy under it.
     def statements(connection, members)
-      [ Grants.narrowed(connection, @role, members),
+      [ Grants.made(connection, @role),
+        Grants.narrowed(connection, @role, members),
         *@whole.map { |table| granted connection, table },
         *@own.map { |table, own| narrowed connection, table, own }, ]
     end

data/lib/omen/version.rb

@@ -1,4 +1,4 @@
 module Omen
   # The version of this gem, as RubyGems knows it.
-  VERSION = '0.7.0'
+  VERSION = '0.9.0'
 end

data/lib/omen.rb

@@ -27,9 +27,27 @@ module Omen
   # @return [void]
   def self.configure = yield config
 
+  # Said where a database refuses one group, since the groups need nothing from one another.
+  REFUSED = 'Skipped, refused by the database: %{statement} (%{error})'
+
   # @return [Array<String>] the environments whose databases a grant should cover.
   def self.environments = Rails.env.development? ? %w[ development test ] : [Rails.env.to_s]
 
+  # A savepoint each and a warning rather than a raise, so a statement a managed database
+  # refuses discards neither the deploy nor the statements behind it -- and what arrives
+  # together is applied together, since a table is never left with row level security on and
+  # no policy under it.
+  # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+  # @param statements [Array<String>] what to run, all of it or none of it.
+  # @return [void]
+  def self.attempted(connection, *statements)
+    connection.transaction(requires_new: true) do
+      statements.each { |statement| connection.execute statement }
+    end
+  rescue ActiveRecord::StatementInvalid => error
+    warn REFUSED % { statement: statements.first.squish, error: error.message.lines.first.strip }
+  end
+
   # @yield [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing connection to each
   #   database this environment prepares.
   # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Claudio Baccigalupo