- Documentation
- Laravel package · Version 0.1
- Automatic synchronisation
Automatic synchronisation
On this page
Each save or deletion of a model queues a job that aligns the remote post with the model: it sends it, replaces it while it has not left, cancels it, or does nothing if the post has not changed.
What triggers it
Each save or deletion of the model (soft deletes included) queues a SyncSocialPost job, on queue.connection and queue.name, once the database transaction commits, unless sync is false. The job carries the type and the key of the model, never the model: it reads the model as it is when it runs, without global scopes, and a soft-deleted model counts as deleted.
Only Eloquent events trigger it: Article::query()->update([...]) or a mass delete synchronises nothing.
The decision table
The job compares the post the model describes with what it already sent, through a fingerprint of the post. The table is read top to bottom: the first line that applies decides. "Forced" is publishToSocial(); "same post" means an unchanged fingerprint.
| Situation | Effect |
|---|---|
| model deleted, or its condition false (unless forced) | the active post is cancelled if it has not left yet |
| invalid data (link, tag, cover, text…) | rejected link and SocialPostRejected, once per error |
| configuration error, or a refusal retrying cannot fix | SocialPostFailed, reported through report() |
publication date older than ignore_older_than (unless forced) |
nothing, logged |
| every network skipped | the active post is cancelled if it has not left yet |
| no network with a destination able to publish | nothing, logged; the active post is left alone |
model deleted or condition false, with a creating link |
looked for by its reference: cancelled if found, else closed (superseded) |
a creating link, same post, schedule ahead, under 23 hours |
the attempt is sent again with its own key |
a creating link otherwise (post changed, schedule gone by, key expired) |
looked for by its reference: completed if found, else closed (superseded) and the post sent anew |
| active post, same post (not forced) | nothing |
| active post, same post, forced | sent again only if it was cancelled or failed in Quiet Social |
| active post not left yet, post changed | it is cancelled, the new one is sent |
| active post cancelled, failed or deleted in Quiet Social, post changed | a new one is sent |
| active post left (or leaving), post changed | nothing is sent; SocialPostOutdated |
last link rejected, same post (not forced) |
nothing: it would be refused again |
| last link cancelled in Quiet Social, same post (not forced) | nothing: someone decided against it |
last link baseline, same post (not forced) |
nothing: the post already existed when the package came |
| three failures in a row, same post (not forced) | nothing, logged |
| otherwise | the post is sent (now, or scheduled) |
A post "has not left" while Quiet Social holds it as draft, pending_approval, approved or scheduled. It is "leaving" when queued or processing, and has "left" once published or partially_published.
The fingerprint covers what the model describes: texts, titles, link, tags, image and alternative text, brand, mode, declared targets (skipped networks removed) and the publication date as written. A cover file enters it through its path, its size and its modification date. A connection that comes back does not change the fingerprint: it covers the declared targets, not the destinations available at that moment.
Sending without publishing twice
Sending first writes the link (creating, with an idempotency key, the effective timing and the brand), then asks the API, then completes the link with the answer. A creating link is an attempt whose answer never came: a lost answer, a crash.
- A retry of the same post, still scheduled ahead and within 23 hours, sends the same key and the same body: the API answers with the publication it already created instead of creating a second one.
- Otherwise (the post has changed, the timing of the attempt has passed, or the API, which keeps a key for 24 hours, may have forgotten it), sending the key again could create a second post: the publication is looked up by its reference, in the brand the attempt was sent for. If found, it completes the link; if not, the link is closed (
superseded) and the post goes out again.
Link dates are stored in the timezone of your application, whatever the timezone the API answered in.
Each new link gets a new key: a post cancelled then sent again unchanged is indeed created again.
Manual publications
Publications sent by hand (the manual builder, a screen of the Filament plugin) are linked without a fingerprint. The synchronisation never cancels nor replaces them.
The lock and the cache
Each synchronisation takes a lock on its model (social:sync:{type}:{key}) in your default cache store, waits lock_wait seconds for it, and puts itself back in the queue when it does not get it. The store must support locks and be shared by every process, web servers and queue workers alike: Redis, Memcached or the database store. The array store, or a file store on several servers, lets two synchronisations of the same model write at once.
A burst of saves queues several jobs: they run one at a time, and the fingerprint makes all the following ones end without any call to the API.
The queue
The sync queue works, but cannot retry a temporary failure: it is logged as a warning, and the post waits for the next save. In production, use a real queue:
- a worker stops a job after 120 seconds only with the
pcntlextension; - give the queue connection a
retry_afterof 150 seconds or more: a shorter one hands the job to a second worker while the first still runs it; - a temporary failure (rate limit, unavailability, the lock of the model already held) is retried for 12 hours, after the
Retry-Afterof the API when it gives one, otherwise after 10 s, 30 s, 1 min, 5 min, then 15 min.
When every attempt has failed, SocialPostFailed is raised and the post waits for the next change of the model.
Old models
A model whose publication date is older than ignore_older_than minutes (1440, a day, by default) is not sent automatically: the save is logged and nothing else happens. publishToSocial() still sends it. A model without a publication date is never too old: on a database of existing models, use social:baseline.
Turning the synchronisation off
QUIET_SOCIAL_SYNC_ENABLED=false (the sync key) turns the synchronisation off everywhere: saves no longer queue anything, and jobs already queued stop without doing anything. This is useful during an import or a seeder. publishToSocial() still works.