Skip to content

chatfuel-lab/wizard / content/modules/publishing/skill

FileKindSize
SKILL.mdskill md3.2 KB
examples/operations.graphqlother8.8 KB
playbooks/customize.mdmarkdown8.8 KB
playbooks/embed.mdmarkdown4.0 KB
references/guide.mdmarkdown12.1 KB
references/library.mdmarkdown4.2 KB
references/scheduler.mdmarkdown9.0 KB

references/scheduler.md

View on GitHub
# Scheduling

## Why this exists at all

The Chatfuel API publishes immediately. No input takes a time, there is no draft
entity, and the only `scheduledPublishTime` in the schema belongs to
`FbPagePost` and is read-only. A content calendar is therefore not a view over
something the platform holds — it is a view over a queue the deployment holds,
and the queue has to be built.

That leaves one honest question: **what is going to run when the time comes?** A
browser is not an answer. A queue that only fires while somebody has a tab open
is a reminder, and calling it a schedule is a lie a customer discovers at
midnight.

So a queue has exactly two shapes, and which one a deployment has decides what
its composer may offer.

## Shape one: local, and honest about it

`setUserStorageItem` is the only persistence this API offers a client — an
arbitrary id holding an arbitrary string, scoped to the **signed-in user**. It
serves one person's drafts perfectly well and nothing else:

- a colleague opening the same bot sees their own drafts, not these;
- nothing reads it but a browser, so a time written into it is a note to self.

An app on this shape offers **save** and **publish now**, and no time control at
all. Not a disabled one with a sentence beside it — absent. The rewrite of a
whole JSON document on every change is fine at queue sizes and needs a cap, so
that a long-running account does not grow a value nobody can save; drop the
oldest already-published entries first, since those are on Instagram anyway.

## Shape two: a database, with something running beside it

The durable shape is a table on the deployment's own Postgres, a job that wakes
up on a timer, and a route that does the publishing. The browser never touches
the database: it calls routes the app's own server serves, that server checks
the caller's session with the gate everything else goes through, and only then
reads or writes.

```
browser ── session bearer ──▶ server routes ── service key ──▶ table
                                     ▲                            │
                                     └──── shared secret ─────  timer job
```

Nine things that this arrangement gets right and a simpler one does not:

1. **Claim before publishing.** Select due rows `for update skip locked`, mark
   them, and only then fire. Two ticks that overlap must not publish the same
   post twice, and a publish here can run for five minutes, so they will
   overlap.
2. **Reap stale claims.** A serverless function killed mid-publish leaves a row
   marked in-flight forever. A second job puts a claim older than about ten
   minutes back, or fails it past a small attempt cap. Without this a single
   killed function is a post that never goes out and never says why.
3. **The response is not the result.** An asynchronous HTTP call from inside
   Postgres records its response separately and can be given up on long before a
   five-minute publish finishes. So the route writes the outcome back itself.
   Design for the request being lost and the work completing.
4. **The callback is authenticated by a secret, not by a session.** There is no
   signed-in user on a timer. One shared secret, stored hashed, compared in
   constant time — and stored as base64 rather than hex, because a scrubber that
   masks 64-hex strings in logs would make it invisible in exactly the logs
   somebody would need.
5. **A protected deployment blocks its own timer.** A host that puts
   authentication in front of every URL blocks an unauthenticated call from a
   database as readily as one from a stranger. Whatever bypass the host offers
   has to be recorded alongside the URL when the deployment registers itself,
   and sent on every callback.
6. **The address is configuration, not something a request says.** Registering
   records where a credential will be posted every minute from then on — the
   callback key, and the bypass above. Deriving that address from the request
   that registered means whoever makes the request chooses it. So the address is
   `PUBLIC_URL` and nothing else: a body field for it is refused,
   `x-forwarded-host` is never read, and `host` is not read either. A platform
   routes by `host` and will usually not deliver a request for a name it does
   not serve, but that is the platform's property rather than this code's, and a
   server run directly answers to whatever name it is handed. A deployment that
   has not said which name it answers to cannot register, and is told so.
7. **The address has to be one the secret survives.** It is registered as
   `https://` and refused otherwise, because the secret rides it in a header
   once a minute for as long as the deployment lives, and over plain http that
   is the credential in the clear on every tick. The one exception is a server
   on this machine (`localhost`, `127.0.0.1`), where there is no wire to read it
   off.
8. **The secret says what happened; it does not say what exists.** The callback
   authenticates a report about a post the scheduler sent out — `attempts` is
   raised by `cf_pub_claim_due` alone and survives the reaper, so a post that
   was never queued cannot be reported published, whatever id the caller names.
   The permalink it stores is handed straight back to a browser as the link to
   the live post, so it is required to be an `https` URL rather than any text at
   all. And the report names the bot the post belongs to, because the secret is
   one value for the whole deployment: without that, the pair of a leaked secret
   and a guessed id writes an outcome onto any post of any bot in the project,
   and with it the reach is the posts of a bot the caller already knew. That is
   what keeps the one `anon`-granted function in this deployment narrow: a
   leaked secret misreports outcomes of one bot, and does not write posts.
9. **Who may register is a question about the deployment, not about a
   workspace.** There is one config row for the whole deployment, so the
   credential is one credential and pointing it somewhere else points it for
   everybody. `role = 'owner'` looks like the right check and guards nothing:
   `cf_claim_workspace` makes every sign-up the owner of the workspace it opens
   for them, so that set is "anybody who registered an account" — and in a
   deployment serving an agency's clients it was the clients from the start. The
   check is `ADMIN_PASSWORD`, the same credential the panel takes: a row that
   belongs to the deployment is written by whoever runs the deployment.

Where the URL comes from is worth stating: it is not known when the app is
scaffolded, because the app has not been deployed yet. It is known once the
deployment has a name, and that is when it goes into `PUBLIC_URL` — after which
an admin opens `/admin`, and the route writes the configured address, the
bypass, and the hash of the shared secret into the config row.

Which is to say that this shape is not publishing's alone. The table and the
functions come with this module, but `ADMIN_PASSWORD` and the page that
registers the deployment are the `admin` module's, and the database under it is
the `auth` module's. An app with publishing and neither of those two composes
and publishes on the spot and has nowhere to put a queue; one with `auth` and no
`admin` has the queue and no way to point the timer at itself. Both are
recommended in the manifest for that reason — the wizard offers them and the
user may decline, and declining is what shape one is for.

## The tables

`cf_pub_posts` holds one row per post: the bot, the kind, the caption, the media
as JSON, the time, the status (`draft | scheduled | publishing | published |
failed`), the claim, the attempts, and — once it exists — Instagram's own id and
permalink. `cf_pub_config` holds one row: where to call back, how to get past the
host's protection, and the hash of the shared secret.

Both follow the same rules as the rest of this project's SQL, and those rules
are not stylistic:

- row-level security on with **no policies**, grants revoked, and `security
  definer` functions as the entire read and write surface. A table PostgREST can
  reach directly is a table a browser can reach directly.
- every function `set search_path = ''`, `execute` revoked from `public`, `anon`
  and `authenticated` and granted back deliberately. New public functions are
  granted to `anon` by default — skipping the revoke is how a private function
  becomes a public one.
- errors raised as `PT4xx` with the machine code in `HINT`, so a client switches
  on a code rather than on a sentence.
- idempotent, so the migration can be re-run over a project that already has it.

## What a schedule still cannot promise

- A timer that skips a tick does not catch up on its own; that is what the reaper
  is for.
- Instagram's own publishing rate limit is not visible from here, so a schedule
  that fires into a throttled account fails at the platform and the failure is
  reported rather than predicted.
- The media URL has to still resolve when the post fires, which may be hours
  later. A link somebody pasted is theirs to keep alive; a bucket the deployment
  controls is the one that will still be there.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall