Added docs and fixes

Signed-off-by: Matteo Collina <[email protected]>

README.md

@@ -9,9 +9,167 @@ Features:
 4. dead letter queue
 5. cron
 
-## Usage
+`@platformatic/pg-hooks` is also useful to create an outbox.
 
-TBD
+![Architecture](./architecture.png)
+
+You can install `@platformatic/pg-hooks` via the [Platformatic Marketplace](https://marketplace.platformatic.dev/).
+
+## Standalone Install & Setup
+
+You can generate a standalone application with: 
+
+```bash
+npx --package @platformatic/pg-hooks -c create-platformatic-pg-hooks
+cd pg-hooks-app
+npm i
+npx plt start
+```
+
+You can then edit your `.env` file and configure the `DB_URL` env variable
+to select a PostgreSQL database.
+
+Explore both the OpenAPI and GraphQL definitions that are now available at [http://127.0.0.1:3042](http://127.0.0.1:3042).
+
+## API Tutorial
+
+To verify everything is working correctly, we will do a short tutorial
+
+### Create a target service
+
+Run:
+
+```bash
+npx @platformatic/service create
+```
+
+This will create a [Platformatic Service](https://docs.platformatic.dev/docs/reference/service/introduction),
+which is essentially a [Fastify](https://fastify.dev) template.
+
+Now, create a `platformatic-service/routes/hook.js` file with the following content:
+
+```js
+/// <reference path="../global.d.ts" />
+'use strict'
+/** @param {import('fastify').FastifyInstance} fastify */
+module.exports = async function (fastify, opts) {
+  fastify.post('/receive-my-hook', async (request, reply) => {
+    request.log.info({ body: request.body }, 'Received hook')
+    return 'ok'
+  })
+}
+```
+
+Then, edit `platformatic-service/.env` and `platformatic-service/.env.sample` so that `PORT=3001`
+
+Run `plt start` to start your app. To verify that your applications is working as expected, in another shell run:
+
+```bash
+curl -X POST -H 'Content-Type: application/json' -d '{ "hello": "world" }' http://127.0.0.1:3001/receive-my-hook
+```
+
+This will print `ok` and log the received body in the console.
+
+### Create a Queue
+
+Create a queue with
+
+```bash
+curl --request POST \
+  --url http://127.0.0.1:3042/queues/ \
+  --header 'Content-Type: application/json' \
+  --data '{
+  "name": "my test",
+  "callbackUrl": "http://127.0.0.1:3001/receive-my-hook",
+  "method": "POST",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "maxRetries": 1
+}'
+```
+
+or via OpenAPI or GraphQL web pages.
+
+### Create a Message
+
+```bash
+curl --request POST \
+  --url http://0.0.0.0:3042/messages/ \
+  --header 'Content-Type: application/json' \
+  --data '{
+  "queueId": 1,
+  "body": "{ \"hello\": \"world\" }"
+}'
+```
+
+Watch the logs in both the service and the hooks app.
+
+### Create a Cron (optional)
+
+You can set up a cron job with:
+
+```bash
+curl --request POST \
+  --url http://0.0.0.0:3042/cron/ \
+  --header 'Content-Type: application/json' \
+  --data '{
+  "queueId": 2,
+  "schedule": "* * * * *",
+  "body": "{ \"hello\": \"world\" }"
+}'
+```
+
+## Authorization
+
+`@platformatic/pg-hooks` is built around [`@platformatic/db`](https://docs.platformatic.dev/docs/reference/db/introduction/#platformatic-db),
+which means that authorization can be set up with its [strategies](https://docs.platformatic.dev/docs/reference/db/authorization/introduction).
+
+The following will configure `@platformatic/pg-hooks` to only accept schedule requests by an admin that knowns the
+`PLT_ADMIN_SECRET` env variable:
+
+```json
+{
+ ...
+ "authorization": {
+    "adminSecret": "{PLT_ADMIN_SECRET}",
+    "rules": [
+      {
+        "role": "anonymous",
+        "entity": "queue",
+        "find": false,
+        "save": false,
+        "delete": false
+      },
+      {
+        "role": "anonymous",
+        "entity": "cron",
+        "find": false,
+        "save": false,
+        "delete": false
+      },
+      {
+        "role": "anonymous",
+        "entity": "message",
+        "find": false,
+        "save": false,
+        "delete": false
+      }
+    ]
+  },
+  ...
+}
+```
+
+For every http request, a `X-PLATFORMATIC-ADMIN-SECRET` header must be set with the same content of `PLT_ADMIN_SECRET`.
+
+## Leader election
+
+`@platformatic/pg-hooks` elects a Leader using a [PostgreSQL Advisory Locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS),
+with a first-comes-win election: the first process that can grab the lock is the leader.
+
+Currently, the leader is responsible for cron scheduling and message delivery, with all the peer responsible for
+creating queues and storing messages in the database.
 
 ## License
 

cli/create.js

@@ -20,8 +20,6 @@ async function execute () {
       dir: join(process.cwd(), 'pg-hooks-app'),
       port: 3042,
       hostname: '0.0.0.0',
-      plugin: true,
-      typescript: false,
       git: false,
       install: true
     }
@@ -32,9 +30,6 @@ async function execute () {
   generator.setConfig({
     port: args.port,
     hostname: args.hostname,
-    plugin: args.plugin,
-    tests: args.plugin,
-    typescript: args.typescript,
     initGitRepository: args.git,
     targetDirectory: args.dir
   })

index.js

@@ -15,7 +15,7 @@ stackable.schema = schema
 stackable.Generator = Generator
 stackable.configManagerConfig = {
   schema,
-  envWhitelist: ['PORT', 'HOSTNAME', 'DATABASE_URL'],
+  envWhitelist: ['PORT', 'HOSTNAME', 'DATABASE_URL', 'DB_URL'],
   allowToWatch: ['.env'],
   schemaOptions: {
     useDefaults: true,

lib/executor.js

@@ -166,7 +166,10 @@ class Executor {
     if ((this.nextTime > 0 && date.getTime() < this.nextTime) || !this.timer) {
       clearTimeout(this.timer)
       this.nextTime = date.getTime()
-      const delay = this.nextTime - Date.now()
+      let delay = this.nextTime - Date.now()
+      if (delay < 0) {
+        delay = 0
+      }
       this.timer = setTimeout(this.execute, delay)
     }
   }

lib/generator.js

@@ -11,6 +11,23 @@ const defaultConnectionString = 'postgres://postgres:[email protected]:5432/pos
 // We extend ServiceGenerator instead of DBGenerator because we
 // do not want to allow users to have their own migrations.
 class PlatformaticPgHooksGenerator extends ServiceGenerator {
+  constructor (opts = {}) {
+    super({
+      ...opts,
+      module: '@platformatic/pg-hooks'
+    })
+  }
+
+  getDefaultConfig () {
+    const res = {
+      ...super.getDefaultConfig(),
+      plugin: false,
+      tests: false
+    }
+
+    return res
+  }
+
   getConfigFieldsDefinitions () {
     const serviceConfigFieldsDefs = super.getConfigFieldsDefinitions()
     return [

migrations/001.do.sql

@@ -28,12 +28,12 @@ CREATE TABLE crons (
 CREATE TABLE messages (
   id SERIAL PRIMARY KEY,
   queue_id INTEGER NOT NULL REFERENCES queues(id),
-  "when" TIMESTAMP NOT NULL,
+  "when" TIMESTAMP DEFAULT NOW(),
   body TEXT,
-  failed BOOLEAN NOT NULL DEFAULT FALSE,
+  failed BOOLEAN DEFAULT FALSE,
   headers JSON,
   sent_at TIMESTAMP,
-  retries INTEGER NOT NULL DEFAULT 0,
+  retries INTEGER DEFAULT 0,
 
   cron_id INTEGER REFERENCES crons(id),