monkrb 0.21.0 → 0.22.0

data/lib/monk/templates/jobs/setup.md

@@ -1,7 +1,7 @@
 ## jobs
 
-Background jobs on the app's own Postgres. A migration creates the queue's
-tables: run `bin/setup_db` and `DB_NAME={{app}}_test bin/setup_db`
+Background jobs on the app's own Postgres. Two migrations create the
+queue's tables and the recurring jobs' one: run `bin/setup_db` and `DB_NAME={{app}}_test bin/setup_db`
 (postgres, above).
 
 ### Run them
@@ -18,6 +18,19 @@ first. `TERM` or Ctrl-C lets the jobs in hand finish before it exits. In
 production it's one more process from the same image, with `bin/jobs` as
 its command.
 
+### Recurring jobs
+
+Declare schedules in `config/recurring.rb`:
+
+```ruby
+Monk::Jobs.recurring "purge_sessions", PurgeSessions, cron: "0 3 * * *"
+```
+
+Cron times are UTC. A running `bin/jobs` enqueues each occurrence once,
+however many are running; with none running, nothing fires, and on
+restart only the latest missed occurrence runs. A new task first runs at
+its next occurrence, not on deploy.
+
 ### Check it works
 
 1. `bundle exec rake test` runs `test/jobs_test.rb`, which enqueues the
@@ -28,3 +41,8 @@ its command.
 3. The example: uncomment the `jobs-enqueue` block in `app/routes/jobs.rb`,
    restart `bin/server`, and
    `curl -X POST "http://localhost:9292/jobs/hello?name=Bob"`.
+4. A recurring job, in a test: `Monk::Jobs.run_scheduler!(at: time)` runs
+   the schedule as if the clock read `time`. The first call only records
+   where the task is; a second call at the next occurrence enqueues it,
+   and `Monk::Jobs.drain!` runs it. The `jobs-recurring` example in
+   `config/recurring.rb` schedules the demo job every hour.

data/lib/monk/templates/websocket/agents.md

@@ -18,6 +18,9 @@ over the transport.
   body, never at a file's top level.
 - Only `bin/websocket_server` calls `listen!`; every other process only
   publishes.
+- A process publishes only once `AppWebSocket.start!` has run:
+  `config/load.rb` calls it, so a script that loads `config/websocket.rb`
+  without it calls it itself, at boot, in the main Ractor.
 - With Postgres, a broadcast is capped at just under 8000 bytes (NOTIFY).
 - `WS_ALLOWED_ORIGINS` must list your pages' origins.
 - Switching transports is three steps in SETUP.md, websocket.

data/lib/monk/templates/websocket/bin/websocket_server

@@ -25,6 +25,10 @@ Monk::Bin.run(__FILE__) do
     exit 1
   end
 
+  # A socket's handler can broadcast too (the websocket-chat example does),
+  # so this process publishes like the others.
+  AppWebSocket.start!
+
   # This process holds the sockets, so it's the only one that listens for
   # what the others publish: the transport's subscriber connection opens
   # here, and an unreachable Postgres or Redis fails right here.

data/lib/monk/templates/websocket/config/websocket_postgres.rb

@@ -6,18 +6,32 @@ require_relative "persistence"
 # The WebSocket registry (monk add websocket): which sockets are subscribed
 # to which topics, and how a broadcast reaches them. bin/server, bin/jobs
 # and bin/websocket_server are separate processes, so Postgres
-# LISTEN/NOTIFY carries a broadcast from one to the others, over the
-# :primary connection's settings (config/persistence.rb). A broadcast is
-# capped at just under 8000 bytes, Postgres's NOTIFY limit. To switch to
-# Redis: SETUP.md, websocket.
+# LISTEN/NOTIFY carries a broadcast from one to the others, on the
+# :primary database (config/persistence.rb). A broadcast is capped at just
+# under 8000 bytes, Postgres's NOTIFY limit. To switch to Redis: SETUP.md,
+# websocket.
+#
+# Broadcasts are published through the :notify pool: one connection per
+# process, however many Ractors publish. Size 1, so a page's updates are
+# sent in the order they were made. Declaring it opens nothing:
+# AppWebSocket.start! does, in every process that publishes (config/load.rb
+# and bin/websocket_server call it).
+Monk::Persistence::Pg.pool(:notify, size: 1)
+
 module AppWebSocket
   TRANSPORT = "postgres".freeze
 
   # A registry over this app's transport. bin/websocket_server's (REGISTRY)
-  # also listens; every other process only publishes.
+  # also listens, on a connection of its own; every other process only
+  # publishes.
   def self.build_registry
-    Monk::WebSocket::PgFanout.new(Monk::WebSocket::Registry.new,
-      pg_opts: Monk::Persistence::Pg.connection_options(:primary),)
+    Monk::WebSocket::PgFanout.new(Monk::WebSocket::Registry.new, db_pool: :notify)
+  end
+
+  # Opens the :notify pool's connection. At boot, in the main Ractor, once
+  # every database and pool is declared.
+  def self.start!
+    Monk::Persistence::Pg.start_pools!(:notify)
   end
 
   REGISTRY = build_registry

data/lib/monk/templates/websocket/config/websocket_redis.rb

@@ -17,5 +17,10 @@ module AppWebSocket
     Monk::WebSocket::RedisFanout.new(Monk::WebSocket::Registry.new, redis_url: Monk::Settings[:redis_url])
   end
 
+  # Nothing to open here: each publishing Ractor connects to Redis on its
+  # first broadcast. config/load.rb and bin/websocket_server call it all
+  # the same, as they would with Postgres.
+  def self.start!; end
+
   REGISTRY = build_registry
 end

data/lib/monk/templates/websocket/setup.md

@@ -24,11 +24,14 @@ connect with `wss://`.
 
 1. If the other one isn't installed, add it: `monk add redis` or
    `monk add postgres`.
-2. In `config/websocket.rb`, swap the fanout: `Monk::WebSocket::RedisFanout`
-   with `redis_url: Monk::Settings[:redis_url]` (and `require_relative
-   "redis"`), or `Monk::WebSocket::PgFanout` with
-   `pg_opts: Monk::Persistence::Pg.connection_options(:primary)` (and
-   `require_relative "persistence"`).
+2. Replace `config/websocket.rb` with Monk's version for the other
+   transport (`redis` or `postgres`), then carry over anything you changed
+   in it:
+
+   ```bash
+   monk help websocket --file config/websocket.rb --transport=redis > config/websocket.rb
+   ```
+
 3. Restart `bin/server`, `bin/websocket_server` and `bin/jobs`.
 
 ### Check it works

data/lib/monk/version.rb

@@ -5,5 +5,5 @@ module Monk
   # class of bug .freeze! guards against for routes/error handlers/models,
   # just on a top-level constant that every worker Ractor reads on boot
   # (found live under kino: GET /hello 500'd until this was frozen).
-  VERSION = "0.21.0".freeze
+  VERSION = "0.22.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkrb
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Matteo Folin
@@ -186,6 +186,7 @@ files:
 - lib/monk/auth/rate_limiter.rb
 - lib/monk/auth/send_login_link.rb
 - lib/monk/auth/session.rb
+- lib/monk/auth/sweep.rb
 - lib/monk/base.rb
 - lib/monk/bin.rb
 - lib/monk/cli.rb
@@ -210,9 +211,13 @@ files:
 - lib/monk/jobs/adapters/pg.rb
 - lib/monk/jobs/args.rb
 - lib/monk/jobs/claim.rb
+- lib/monk/jobs/cron.rb
 - lib/monk/jobs/errors.rb
+- lib/monk/jobs/firing.rb
 - lib/monk/jobs/job.rb
+- lib/monk/jobs/recurring_task.rb
 - lib/monk/jobs/runtime.rb
+- lib/monk/jobs/scheduler.rb
 - lib/monk/jobs/worker.rb
 - lib/monk/live.rb
 - lib/monk/live/client/idiomorph.LICENSE
@@ -254,6 +259,8 @@ files:
 - lib/monk/templates/auth/config/auth.rb
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.down.sql
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.up.sql
+- lib/monk/templates/auth/db/migrate/00000000000004_create_login_requests.down.sql
+- lib/monk/templates/auth/db/migrate/00000000000004_create_login_requests.up.sql
 - lib/monk/templates/auth/setup.md
 - lib/monk/templates/auth/test/auth_test.rb
 - lib/monk/templates/base/.dockerignore
@@ -288,8 +295,11 @@ files:
 - lib/monk/templates/jobs/app/routes/jobs.rb
 - lib/monk/templates/jobs/bin/jobs
 - lib/monk/templates/jobs/config/jobs.rb
+- lib/monk/templates/jobs/config/recurring.rb
 - lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.down.sql
 - lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.up.sql
+- lib/monk/templates/jobs/db/migrate/00000000000003_create_recurring_tables.down.sql
+- lib/monk/templates/jobs/db/migrate/00000000000003_create_recurring_tables.up.sql
 - lib/monk/templates/jobs/setup.md
 - lib/monk/templates/jobs/test/jobs_test.rb
 - lib/monk/templates/live/agents.md