bible270 1.17.2 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,406 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'digest'
4
+ require 'json'
5
+ require 'securerandom'
6
+ require 'uri'
7
+ require 'bible270/plan'
8
+
9
+ module Bible270
10
+ module ProgressSync
11
+ class Error < StandardError; end
12
+ class ConfigurationError < Error; end
13
+ class Unavailable < Error; end
14
+ class Conflict < Error; end
15
+ class Unauthorized < Error; end
16
+
17
+ autoload :Client, 'bible270/progress_sync/client'
18
+
19
+ MAX_ATTEMPTS = 8
20
+ LEASE_SECONDS = 300
21
+ SUPPRESSION_KEY = :bible270_progress_sync_suppressed
22
+
23
+ module_function
24
+
25
+ def available?
26
+ return false unless defined?(ActiveRecord::Base)
27
+
28
+ connection = ActiveRecord::Base.connection
29
+ %w[bible270_progress_sync_links bible270_progress_sync_deliveries bible270_participations].all? do |table|
30
+ connection.data_source_exists?(table)
31
+ end && connection.column_exists?(:bible270_participations, :progress_sync_generation)
32
+ rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
33
+ false
34
+ end
35
+
36
+ # Recompute from the actual schedule, not the gem version or a long-lived
37
+ # digest cache. Include empty readings and the positional checkoff semantics.
38
+ def fingerprint
39
+ schedule = (1..Plan::DAYS).map do |day|
40
+ [day, Plan::TRACKS.keys.sort.map { |track| [track, Plan.parts_for(day, track).each_with_index.map { |text, part| [part, text] }] }]
41
+ end
42
+ Digest::SHA256.hexdigest(JSON.generate(['bible270:completion:day-one-based:part-zero-based:v1', schedule]))
43
+ end
44
+
45
+ def suppress
46
+ previous = Thread.current.thread_variable_get(SUPPRESSION_KEY)
47
+ Thread.current.thread_variable_set(SUPPRESSION_KEY, true)
48
+ yield
49
+ ensure
50
+ Thread.current.thread_variable_set(SUPPRESSION_KEY, previous)
51
+ end
52
+
53
+ def suppressed? = !!Thread.current.thread_variable_get(SUPPRESSION_KEY)
54
+
55
+ # Called inside the local checkoff transaction; never contacts the client.
56
+ # Returning an array also supports several allowlisted destinations per reader.
57
+ def capture(participation, readings)
58
+ return [] if suppressed? || !destinations.is_a?(Hash) || destinations.empty? || !available? || !participation&.persisted?
59
+
60
+ links = ProgressSyncLink.active.where(participation_id: participation.id)
61
+ return [] unless links.exists?
62
+
63
+ triples = normalize_readings(readings)
64
+ return [] if triples.empty?
65
+
66
+ captured = []
67
+ with_source_lock(participation) do |membership|
68
+ digest = fingerprint
69
+ links.order(:id).lock.each do |link|
70
+ validate_link!(link, membership: membership, digest: digest)
71
+ unless membership.progress_sync_generation == participation.progress_sync_generation
72
+ raise Conflict, 'Source membership changed; explicitly relink this reader'
73
+ end
74
+
75
+ captured << enqueue!(link, triples)
76
+ rescue ConfigurationError, Conflict, Unauthorized => e
77
+ pause!(link, e.message)
78
+ end
79
+ end
80
+ captured
81
+ end
82
+
83
+ def lookup(destination:, email:)
84
+ ensure_available!
85
+ ensure_network_outside_transaction!
86
+ configured_destination!(destination)
87
+ Client.new(destination.to_s).lookup(normalize_email(email))
88
+ end
89
+
90
+ # A paused link is replaced, never reactivated or retargeted. The caller's
91
+ # confirmation of this API is the explicit consent to create the replacement.
92
+ def link!(reader:, destination:, remote:, expected_participation_id:)
93
+ ensure_available!
94
+ destination = destination.to_s
95
+ destination_settings = configured_destination!(destination)
96
+ remote = remote.to_h.transform_keys(&:to_s)
97
+ digest = fingerprint
98
+ raise Conflict, 'Destination uses a different reading plan' unless remote['plan_fingerprint'] == digest
99
+
100
+ attributes = {
101
+ destination: destination, destination_url: destination_settings.fetch(:url), plan_fingerprint: digest,
102
+ remote_reader_id: remote_integer!(remote, 'reader_id', minimum: 1),
103
+ remote_participation_id: remote_integer!(remote, 'participation_id', minimum: 1),
104
+ remote_generation: remote_integer!(remote, 'generation', minimum: 0),
105
+ remote_name: remote['name'].to_s.strip, email: normalize_email(remote['email'])
106
+ }
107
+ membership = Participation.find_by(id: expected_participation_id, reader_id: reader.id)
108
+ raise Conflict, 'Source membership changed; reload before linking' unless membership
109
+
110
+ result = nil
111
+ with_source_lock(membership) do |current|
112
+ validate_membership!(current)
113
+ raise Conflict, 'Reading plan changed; look up the destination again' unless fingerprint == digest
114
+ raise ConfigurationError, 'Destination URL changed; look up the destination again' unless configured_destination!(destination) == destination_settings
115
+
116
+ existing = ProgressSyncLink.active.where(participation_id: current.id, destination: destination).lock.first
117
+ if existing
118
+ begin
119
+ validate_link!(existing, membership: current, digest: digest)
120
+ binding_changed = %i[remote_reader_id remote_participation_id remote_generation].any? do |attribute|
121
+ existing.public_send(attribute) != attributes.fetch(attribute)
122
+ end
123
+ pause!(existing, 'Destination reader binding changed; explicitly replaced') if binding_changed
124
+ rescue ConfigurationError, Conflict, Unauthorized => e
125
+ pause!(existing, e.message)
126
+ end
127
+ end
128
+ result = ProgressSyncLink.create!(attributes.merge(participation: current,
129
+ source_generation: current.progress_sync_generation))
130
+ end
131
+ result
132
+ end
133
+
134
+ # Add-only snapshot. Repeating this is safe: destination checkoff uniqueness
135
+ # is the idempotency boundary. No local progress or dates are changed.
136
+ # Returns the new delivery, or nil when the current snapshot is empty.
137
+ def copy_existing!(link)
138
+ ensure_available!
139
+ return nil if suppressed?
140
+
141
+ result = nil
142
+ failure = nil
143
+ with_source_lock(link.participation) do |membership|
144
+ link.reload.lock!
145
+ begin
146
+ validate_link!(link, membership: membership)
147
+ triples = normalize_readings(membership.checkoffs.order(:day, :track, :part).pluck(:day, :track, :part))
148
+ result = enqueue!(link, triples) if triples.any?
149
+ rescue ConfigurationError, Conflict, Unauthorized => e
150
+ pause!(link, e.message)
151
+ failure = e
152
+ end
153
+ end
154
+ # Raise after committing the pause, including when an admin repeats copy.
155
+ raise failure if failure
156
+
157
+ result
158
+ end
159
+
160
+ def link_usable?(link)
161
+ return false unless available?
162
+
163
+ validate_link!(link)
164
+ true
165
+ rescue Error, ActiveRecord::RecordNotFound
166
+ false
167
+ end
168
+
169
+ # Returns successful delivery count, not reading count. Scheduling this task
170
+ # frequently is sufficient; there is no job adapter dependency.
171
+ def deliver_pending(limit: 100, delivery_id: nil)
172
+ return 0 unless available?
173
+
174
+ ensure_network_outside_transaction!
175
+ count = 0
176
+ pending = ProgressSyncDelivery.due.where(progress_sync_link_id: ProgressSyncLink.active.select(:id))
177
+ pending = pending.where(id: delivery_id) unless delivery_id.nil?
178
+ pending.order(:next_attempt_at, :id).limit(limit).pluck(:id).each do |id|
179
+ claimed = claim_delivery(id)
180
+ next unless claimed
181
+
182
+ delivery, exhausted = claimed
183
+ begin
184
+ raise Conflict, 'Delivery retry limit reached; explicitly relink to retry' if exhausted
185
+
186
+ link = prepare_delivery!(delivery)
187
+ # No transaction or row lock survives prepare_delivery!. Tokens fence
188
+ # late HTTP responses if an expired lease was reclaimed by a worker.
189
+ response = Client.new(link.destination).complete(link, delivery.readings)
190
+ counts = response_counts!(response, expected_count: delivery.readings.uniq.length)
191
+ count += 1 if finish_delivery!(delivery, counts: counts)
192
+ rescue Error => e
193
+ finish_delivery!(delivery, error: e)
194
+ end
195
+ end
196
+ count
197
+ end
198
+
199
+ def destinations
200
+ config = Bible270.config
201
+ config.respond_to?(:progress_sync_destinations) ? (config.progress_sync_destinations || {}) : {}
202
+ end
203
+ private_class_method :destinations
204
+
205
+ def ensure_available!
206
+ raise Unavailable, 'Progress sync migration is not installed' unless available?
207
+ end
208
+ private_class_method :ensure_available!
209
+
210
+ def ensure_network_outside_transaction!
211
+ return unless ActiveRecord::Base.connection.transaction_open?
212
+
213
+ raise ConfigurationError, 'Progress sync HTTP cannot run inside a database transaction'
214
+ end
215
+ private_class_method :ensure_network_outside_transaction!
216
+
217
+ def normalize_email(email)
218
+ value = email.to_s.strip.downcase
219
+ raise Conflict, 'A valid destination reader email is required' unless value.match?(%r{\A[^@\s]+@[^@\s]+\z})
220
+
221
+ value
222
+ end
223
+ private_class_method :normalize_email
224
+
225
+ def configured_destination!(destination)
226
+ config = Bible270.config
227
+ unless config.respond_to?(:progress_sync_instance_id) && config.progress_sync_instance_id.to_s.strip.present?
228
+ raise ConfigurationError, 'A progress sync source instance ID is required'
229
+ end
230
+
231
+ entries = destinations
232
+ raise ConfigurationError, 'Progress sync destinations must be an allowlist hash' unless entries.is_a?(Hash)
233
+
234
+ entry = entries[destination.to_s]
235
+ raise ConfigurationError, 'Destination is not allowlisted' unless entry.is_a?(Hash)
236
+
237
+ url = (entry[:url] || entry['url']).to_s.chomp('/')
238
+ secret = (entry[:secret] || entry['secret']).to_s
239
+ uri = URI.parse(url)
240
+ unless uri.is_a?(URI::HTTPS) && uri.host.present? && !uri.userinfo && !uri.query && !uri.fragment && secret.length >= 32
241
+ raise ConfigurationError, 'Destination requires an HTTPS mount URL and a secret of at least 32 characters'
242
+ end
243
+
244
+ { url: url, secret: secret }
245
+ rescue URI::InvalidURIError
246
+ raise ConfigurationError, 'Destination URL is invalid'
247
+ end
248
+ private_class_method :configured_destination!
249
+
250
+ def remote_integer!(remote, key, minimum:)
251
+ value = Integer(remote.fetch(key).to_s, 10)
252
+ raise ArgumentError if value < minimum
253
+
254
+ value
255
+ rescue KeyError, ArgumentError
256
+ raise Conflict, "Destination returned an invalid #{key}"
257
+ end
258
+ private_class_method :remote_integer!
259
+
260
+ def normalize_readings(readings)
261
+ Array(readings).map do |triple|
262
+ unless triple.is_a?(Array) && triple.length == 3
263
+ raise Conflict, 'Readings must be [day, track, part] triples'
264
+ end
265
+
266
+ day, track, part = triple
267
+ unless Plan.valid_day?(day) && Plan::TRACKS.key?(track) && Plan.valid_part?(day, track, part)
268
+ raise Conflict, 'A completion does not belong to the current reading plan'
269
+ end
270
+
271
+ [day, track, part]
272
+ end.uniq
273
+ end
274
+ private_class_method :normalize_readings
275
+
276
+ def with_source_lock(participation)
277
+ # Fresh instances avoid stale association caches and lock! rejecting a
278
+ # caller's dirty Reader. Match archive/restart's run -> reader lock order.
279
+ PlanRun.find(participation.plan_run_id).with_lock do
280
+ Reader.find(participation.reader_id).with_lock do
281
+ yield Participation.find(participation.id)
282
+ end
283
+ end
284
+ end
285
+ private_class_method :with_source_lock
286
+
287
+ def validate_membership!(membership)
288
+ unless membership.active? && PlanRun.where(id: membership.plan_run_id, current: true).exists? &&
289
+ Participation.chosen.where(id: membership.id).exists?
290
+ raise Conflict, 'Source reader is no longer active in the linked run; explicitly relink'
291
+ end
292
+ end
293
+ private_class_method :validate_membership!
294
+
295
+ def validate_link!(link, membership: nil, digest: nil)
296
+ raise Conflict, 'Progress sync link is paused; explicitly relink' unless link.active?
297
+
298
+ membership ||= Participation.find(link.participation_id)
299
+ validate_membership!(membership)
300
+ unless membership.id == link.participation_id && membership.progress_sync_generation == link.source_generation
301
+ raise Conflict, 'Source membership generation changed; explicitly relink'
302
+ end
303
+ raise Conflict, 'Reading plan changed; explicitly relink' unless link.plan_fingerprint == (digest || fingerprint)
304
+ unless configured_destination!(link.destination).fetch(:url) == link.destination_url
305
+ raise ConfigurationError, 'Destination URL changed; explicitly relink'
306
+ end
307
+
308
+ true
309
+ end
310
+ private_class_method :validate_link!
311
+
312
+ def enqueue!(link, triples)
313
+ link.deliveries.create!(readings: triples, next_attempt_at: Time.current)
314
+ end
315
+ private_class_method :enqueue!
316
+
317
+ def pause!(link, message)
318
+ link.update!(state: 'paused', last_error: message.to_s.truncate(1000))
319
+ end
320
+ private_class_method :pause!
321
+
322
+ def claim_delivery(id)
323
+ delivery = ProgressSyncDelivery.find_by(id: id)
324
+ return unless delivery
325
+
326
+ now = Time.current
327
+ token = SecureRandom.uuid
328
+ attempts = delivery.attempts
329
+ # A single compare-and-swap UPDATE works on SQLite as well as PostgreSQL;
330
+ # no select-lock transaction is held while contacting the destination.
331
+ claimed = ProgressSyncDelivery.due(now).where(id: id, attempts: attempts,
332
+ progress_sync_link_id: ProgressSyncLink.active.select(:id)).update_all(
333
+ claim_token: token, locked_until: now + LEASE_SECONDS,
334
+ attempts: [attempts + 1, MAX_ATTEMPTS].min, updated_at: now
335
+ )
336
+ return unless claimed == 1
337
+
338
+ delivery.reload
339
+ # Another worker can reclaim only after lease expiry. Do not use its token.
340
+ return unless delivery.claim_token == token
341
+
342
+ [delivery, attempts >= MAX_ATTEMPTS]
343
+ end
344
+ private_class_method :claim_delivery
345
+
346
+ def prepare_delivery!(delivery)
347
+ link = ProgressSyncLink.find(delivery.progress_sync_link_id)
348
+ with_source_lock(link.participation) do |membership|
349
+ link.reload.lock!
350
+ validate_link!(link, membership: membership)
351
+ normalize_readings(delivery.readings)
352
+ unless ProgressSyncDelivery.where(id: delivery.id, claim_token: delivery.claim_token, delivered_at: nil)
353
+ .where('locked_until > ?', Time.current).exists?
354
+ raise Unavailable, 'Delivery lease expired before sending'
355
+ end
356
+ end
357
+ link
358
+ rescue ActiveRecord::RecordNotFound
359
+ raise Conflict, 'Source membership or progress sync link no longer exists'
360
+ end
361
+ private_class_method :prepare_delivery!
362
+
363
+ def response_counts!(response, expected_count:)
364
+ counts = %w[added existing].map { |key| response.fetch(key) }
365
+ unless counts.all? { |value| value.is_a?(Integer) && value >= 0 } && counts.sum == expected_count
366
+ raise Unavailable, 'Destination returned invalid completion counts'
367
+ end
368
+
369
+ counts
370
+ rescue KeyError, NoMethodError
371
+ raise Unavailable, 'Destination returned invalid completion counts'
372
+ end
373
+ private_class_method :response_counts!
374
+
375
+ def finish_delivery!(delivery, counts: nil, error: nil)
376
+ finished = false
377
+ ProgressSyncLink.transaction do
378
+ link = ProgressSyncLink.lock.find_by(id: delivery.progress_sync_link_id)
379
+ next unless link
380
+
381
+ current = ProgressSyncDelivery.lock.find_by(id: delivery.id, claim_token: delivery.claim_token, delivered_at: nil)
382
+ next unless current
383
+
384
+ now = Time.current
385
+ if error
386
+ message = error.message.to_s.truncate(1000)
387
+ current.update!(last_error: message, claim_token: nil, locked_until: nil,
388
+ next_attempt_at: now + [60 * (2**(current.attempts - 1)), 21_600].min)
389
+ if !error.is_a?(Unavailable) || current.attempts >= MAX_ATTEMPTS
390
+ pause!(link, message)
391
+ elsif link.active?
392
+ link.update!(last_error: message)
393
+ end
394
+ else
395
+ current.update!(delivered_at: now, last_error: nil, claim_token: nil, locked_until: nil)
396
+ attributes = { last_synced_at: now, last_added: counts[0], last_existing: counts[1] }
397
+ attributes[:last_error] = nil if link.active?
398
+ link.update!(attributes)
399
+ finished = true
400
+ end
401
+ end
402
+ finished
403
+ end
404
+ private_class_method :finish_delivery!
405
+ end
406
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Bible270
4
- VERSION = '1.17.2'
4
+ VERSION = '1.18.0'
5
5
  end
data/lib/bible270.rb CHANGED
@@ -15,6 +15,7 @@ require 'bible270/translations'
15
15
  require 'bible270/favicon'
16
16
  require 'bible270/scripture_frames'
17
17
  require 'bible270/configuration'
18
+ require 'bible270/progress_sync'
18
19
  require 'bible270/daily_reminders'
19
20
  require 'bible270/reader_consistency'
20
21
  require 'bible270/reader_progress_report'
@@ -51,6 +51,18 @@ Bible270.configure do |config|
51
51
  # config.mailer_host = 'example.com' # lets the notice link to the reader
52
52
  # config.registration_notice_deliver_later = true # needs Active Job
53
53
 
54
+ # --- Progress sync (optional) ---------------------------------------------
55
+ # Admin-managed one-way check-offs between trusted installations. See README.
56
+ # config.progress_sync_instance_id = 'primary'
57
+ # config.progress_sync_destinations = {
58
+ # 'church' => { label: 'Church', url: 'https://church.example/daily-bread',
59
+ # secret: ENV.fetch('B270_PRIMARY_CHURCH_SYNC_SECRET') }
60
+ # }
61
+ # On the receiving installation, authorize that source with the same secret:
62
+ # config.progress_sync_sources = { 'primary' => { secret: ENV.fetch('B270_PRIMARY_CHURCH_SYNC_SECRET') } }
63
+ # Schedule bible270:progress_sync:deliver every minute on the primary.
64
+ # config.progress_sync_deliver_later = true # optional: persistent Active Job backend + worker
65
+
54
66
  # --- Start date ------------------------------------------------------------
55
67
  # Community-wide start date (Date, Time, or "YYYY-MM-DD"), or nil for undated.
56
68
  # config.start_date = Date.new(2026, 9, 6)
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bible270/progress_sync'
4
+
5
+ namespace :bible270 do
6
+ namespace :progress_sync do
7
+ desc 'Deliver due one-way Bible270 progress sync outbox entries (schedule regularly)'
8
+ task deliver: :environment do
9
+ count = Bible270::ProgressSync.deliver_pending
10
+ puts "Delivered #{count} progress sync #{'delivery'.pluralize(count)}."
11
+ end
12
+ end
13
+ end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bible270
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.17.2
4
+ version: 1.18.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Andrew vonderLuft
@@ -143,6 +143,7 @@ files:
143
143
  - README.md
144
144
  - Rakefile
145
145
  - app/controllers/bible270/admin_controller.rb
146
+ - app/controllers/bible270/admin_progress_syncs_controller.rb
146
147
  - app/controllers/bible270/admin_roles_controller.rb
147
148
  - app/controllers/bible270/admin_scripture_frames_controller.rb
148
149
  - app/controllers/bible270/application_controller.rb
@@ -151,10 +152,12 @@ files:
151
152
  - app/controllers/bible270/days_controller.rb
152
153
  - app/controllers/bible270/likes_controller.rb
153
154
  - app/controllers/bible270/profiles_controller.rb
155
+ - app/controllers/bible270/progress_sync_controller.rb
154
156
  - app/controllers/bible270/readers_controller.rb
155
157
  - app/controllers/bible270/scripture_frames_controller.rb
156
158
  - app/controllers/bible270/sessions_controller.rb
157
159
  - app/helpers/bible270/plan_helper.rb
160
+ - app/jobs/bible270/progress_sync_job.rb
158
161
  - app/mailers/bible270/application_mailer.rb
159
162
  - app/mailers/bible270/broadcast.html.erb
160
163
  - app/mailers/bible270/broadcast.text.erb
@@ -166,10 +169,13 @@ files:
166
169
  - app/models/bible270/like.rb
167
170
  - app/models/bible270/participation.rb
168
171
  - app/models/bible270/plan_run.rb
172
+ - app/models/bible270/progress_sync_delivery.rb
173
+ - app/models/bible270/progress_sync_link.rb
169
174
  - app/models/bible270/reader.rb
170
175
  - app/models/bible270/scripture_frame.rb
171
176
  - app/models/bible270/setting.rb
172
177
  - app/models/bible270/sign_in_token.rb
178
+ - app/views/bible270/admin/_progress_sync.html.erb
173
179
  - app/views/bible270/admin/_reader_list.html.erb
174
180
  - app/views/bible270/admin/_scripture_frames.html.erb
175
181
  - app/views/bible270/admin/_scripture_text.html.erb
@@ -275,6 +281,7 @@ files:
275
281
  - db/migrate/20260101000025_add_admin_to_bible270_readers.rb
276
282
  - db/migrate/20260101000026_add_revert_to_bible270_plan_runs.rb
277
283
  - db/migrate/20260101000027_create_bible270_scripture_frames.rb
284
+ - db/migrate/20260101000028_create_bible270_progress_sync.rb
278
285
  - lib/bible270.rb
279
286
  - lib/bible270/avatar_backfill.rb
280
287
  - lib/bible270/avatar_images.rb
@@ -290,6 +297,9 @@ files:
290
297
  - lib/bible270/migration_reconciler.rb
291
298
  - lib/bible270/names.rb
292
299
  - lib/bible270/plan.rb
300
+ - lib/bible270/progress_sync.rb
301
+ - lib/bible270/progress_sync/authentication.rb
302
+ - lib/bible270/progress_sync/client.rb
293
303
  - lib/bible270/reader_consistency.rb
294
304
  - lib/bible270/reader_progress_report.rb
295
305
  - lib/bible270/scripture_frames.rb
@@ -303,6 +313,7 @@ files:
303
313
  - lib/tasks/bible270_avatars.rake
304
314
  - lib/tasks/bible270_migrations.rake
305
315
  - lib/tasks/bible270_notifications.rake
316
+ - lib/tasks/bible270_progress_sync.rake
306
317
  - lib/tasks/bible270_readers.rake
307
318
  - lib/tasks/bible270_reminders.rake
308
319
  homepage: https://github.com/avonderluft/bible270