@shortlink-org/portolan 0.1.0

package/plugins/extract-asyncapi/spec.go

@@ -0,0 +1,151 @@
+package main
+
+import (
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// The document is read as a node tree rather than into structs, for the reason
+// the OpenAPI extractor gives beside its own reader: a mapping unmarshalled
+// into a Go map loses the order its author wrote, and a channel object holds
+// keys this does not model, which walking the nodes ignores rather than fails
+// on.
+//
+// Two versions have to be read here, and they disagree about a word. In 3.x an
+// operation says `action: send` or `action: receive`, from the application's
+// side, and that is the end of it. In 2.x a channel has `publish` and
+// `subscribe`, and both are written from the *client's* side: `publish` is what
+// somebody else publishes to the application, and `subscribe` is what the
+// application produces for somebody else to subscribe to. Reading 2.x the
+// obvious way gets every arrow backwards, which is the confusion 3.x was
+// changed to end.
+
+type document struct {
+	root *yaml.Node
+	path string
+	// major is the major version of the document: 2 or 3.
+	major int
+}
+
+func load(path string) (*document, error) {
+	contents, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	var root yaml.Node
+	if err := yaml.Unmarshal(contents, &root); err != nil {
+		return nil, err
+	}
+
+	node := &root
+	if node.Kind == yaml.DocumentNode && len(node.Content) > 0 {
+		node = node.Content[0]
+	}
+
+	doc := &document{root: node, path: path, major: 3}
+	if version := text(child(node, "asyncapi")); strings.HasPrefix(version, "2.") {
+		doc.major = 2
+	}
+
+	return doc, nil
+}
+
+// entry is one key/value pair of a mapping, in document order.
+type entry struct {
+	key   string
+	value *yaml.Node
+}
+
+func entries(node *yaml.Node) []entry {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return nil
+	}
+
+	out := make([]entry, 0, len(node.Content)/2)
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		out = append(out, entry{key: node.Content[i].Value, value: node.Content[i+1]})
+	}
+
+	return out
+}
+
+// child follows a path of mapping keys, and answers nil for anything missing.
+func child(node *yaml.Node, keys ...string) *yaml.Node {
+	for _, key := range keys {
+		found := false
+		for _, e := range entries(node) {
+			if e.key == key {
+				node = e.value
+				found = true
+
+				break
+			}
+		}
+		if !found {
+			return nil
+		}
+	}
+
+	return node
+}
+
+func text(node *yaml.Node) string {
+	if node == nil {
+		return ""
+	}
+
+	return strings.TrimSpace(node.Value)
+}
+
+// items reads a sequence, or the single node written where a sequence was
+// allowed. A document that names one message where it could have named several
+// is the common case, and both spellings mean the same thing.
+func items(node *yaml.Node) []*yaml.Node {
+	if node == nil {
+		return nil
+	}
+	if node.Kind != yaml.SequenceNode {
+		return []*yaml.Node{node}
+	}
+
+	return node.Content
+}
+
+// deref follows a local $ref, and answers the node itself when there is none.
+//
+// Only local refs are followed. A document that reaches into another file is
+// describing something this extractor cannot see, and guessing at a name from
+// the last segment of a path would be inventing one.
+func (d *document) deref(node *yaml.Node) (*yaml.Node, string) {
+	ref := text(child(node, "$ref"))
+	if ref == "" {
+		return node, ""
+	}
+	if !strings.HasPrefix(ref, "#/") {
+		return nil, ref
+	}
+
+	var keys []string
+	for _, segment := range strings.Split(strings.TrimPrefix(ref, "#/"), "/") {
+		// JSON Pointer escapes, which a channel address containing a slash
+		// needs: `shop~1cart` is one key, not two.
+		segment = strings.ReplaceAll(segment, "~1", "/")
+		keys = append(keys, strings.ReplaceAll(segment, "~0", "~"))
+	}
+
+	return child(d.root, keys...), ref
+}
+
+// refKey is the last segment of a ref, which is the key the thing it points at
+// is filed under.
+func refKey(ref string) string {
+	at := strings.LastIndex(ref, "/")
+	if at < 0 {
+		return ref
+	}
+
+	return strings.ReplaceAll(strings.ReplaceAll(ref[at+1:], "~1", "/"), "~0", "~")
+}

package/plugins/extract-celery/README.md

@@ -0,0 +1,169 @@
+# extract-celery
+
+A tree with Celery in it in, work queues and job flows out. The Python twin of
+`extract-river`: it does not need aggregates, does not treat a task as a
+domain event, and answers with a channel of kind `job` per queue and a two-hop
+flow per task — the call that enqueues it, and the worker that runs it.
+
+Written in Python and run as a process plugin, `python3 plugins/extract-celery/main.py`.
+Python 3.9 or newer and nothing but the standard library; the protocol, the
+tree reader and the fragment shapes are `plugins/pyplugin`, shared with
+`extract-django` — and so are the task and configuration readers,
+`celery_tasks.py` and `celery_conf.py`, which is how an enqueue inside a
+Django flow lands on the same `celery-<queue>` participant this plugin's flow
+draws. **The project is never imported**, and neither is Celery:
+everything is read through `ast`, and names are resolved by import and by
+file.
+
+## What it reads
+
+**A task** is a module-level function decorated `@shared_task`, `@app.task`
+or `@<anything>.task`, with or without arguments. Its wire name is the
+`name=` it was given, or what Celery composes when it was not: the module's
+dotted path and the function's name, `invoices.tasks.send_invoice_email`. A
+`queue=` on the decorator is where it goes unless a call says otherwise. The
+doc is the docstring, first paragraph. A class-based task is not read.
+
+**An enqueue** is `t.delay(...)`, `t.apply_async(...)`, or either through a
+signature, `t.s(...).apply_async()`. A `chain`, `group` or `chord` holds
+several signatures; each is recorded as an enqueue, noted with the canvas it
+sits in, and the order the canvas imposes is not drawn. `app.send_task("name")`
+enqueues by wire name, for a task that may live in another tree.
+`transaction.on_commit(lambda: t.delay(...))` — and the `partial` form — is
+the same enqueue with the note that it waits for the commit, which is the one
+fact about *when* a message leaves that the code states plainly. A
+`countdown=` or an `eta=` is noted too. Every module of the tree is searched:
+services, views, receivers, other tasks.
+
+**A schedule** is what the clock sets off: an entry of `beat_schedule` —
+`CELERY_BEAT_SCHEDULE` in the settings, `app.conf.beat_schedule`, the legacy
+`CELERYBEAT_SCHEDULE` — or a call of `add_periodic_task(schedule, task.s(),
+name=...)`, wherever it is made, usually under `@app.on_after_configure.connect`.
+The entry names the task on the wire, the call names it through its
+signature, and `options={"queue": ...}` or a `queue=` on the call places it
+before the task's own queue. The schedule object is read into a sentence:
+`crontab(minute=0, hour="*/3")` is `cron 0 */3 * * *` in crontab's own field
+order with `*` for what is not said, a number of seconds or a `timedelta` is
+`every 6h`, `solar("sunset", …)` is `solar sunset`; anything else is kept as
+written and said to be unreadable. Beat is a producer like any other, so a
+task only the clock enqueues is not reported as one nothing enqueues. A
+project with `django_celery_beat` installed keeps its schedule in the
+database, which is said once and not read.
+
+**The queue** is decided the way Celery decides it: the `queue=` at the call,
+then the decorator's, then `task_routes` — an exact name before a glob, in the
+order written — then `task_default_queue`, and past all of those Celery's own
+`celery`. Each message says which rule placed it.
+
+**The configuration** is read from two places, the settings first and the app
+module over them, which is the order Celery applies them in. The app module
+is wherever `X = Celery(...)` is assigned; its `config_from_object(...,
+namespace="CELERY")` names the prefix the settings are read under, and its
+`X.conf.update(...)` and `X.conf.key = ...` are read as written. The settings
+module is what `manage.py` sets `DJANGO_SETTINGS_MODULE` to, or the `settings`
+option. Three keys matter — `task_routes`, `task_default_queue`, `broker_url`
+— and the pre-4.0 spellings of them are accepted. A value is read as far as
+syntax carries it: a literal, the default of `os.environ.get("X", default)`,
+a module-level constant followed once. A router function is not run, and is
+said not to be.
+
+## What comes out
+
+One `channel` per queue, `kind: "job"`, `address` the queue, one message per
+task on it: `send` when this tree enqueues it, `receive` when this tree
+declares it. The doc of the `receive` says which rule placed it. The kind is
+what lets many callers enqueue one task without the merge calling them rival
+publishers, and what keeps a task out of the Problems page's search for a
+domain event with the same wire name.
+
+One `flow` per task that is both enqueued and declared here: `service →
+broker : call enqueue <task>` at the first call in path order, with the
+others named in the note, then `broker → service : call <task>` at the
+function. The broker participant is `celery-<queue>`. Every step is
+`declared`. Both steps carry the exact Celery queue and task wire name as a
+job handoff. This lets a Django endpoint flow that calls `.delay()` or
+`.apply_async()` continue at the corresponding worker step without repeating
+the enqueue.
+
+The worker step also carries the task function's source entrypoint. When the
+Django extractor reads the same tree, enrichment appends the task body's
+database, event and API effects after that receive step. This produces one
+continuous synchronous-to-asynchronous scenario while keeping Celery as the
+owner of queue and routing facts.
+
+One more `flow` per task the clock sets off: `celery-beat → broker : call
+enqueue <task>` at the entry, then the same worker step, with the trigger
+`scheduled` and the schedule as its label. A task the code also enqueues
+keeps that flow and gets this one beside it, told apart by `-beat` in the
+slug — what happens when the clock fires and what happens when a request does
+are two different questions, and a reader asks them separately.
+
+## What it does not read
+
+Named here rather than left to be discovered: **a schedule kept in the
+database** (`django_celery_beat`), **task bodies when no Django extractor is
+paired with this plugin**, **retries, rate
+limits and time limits**, **the result backend**, **task
+priority**, a **router function** in `task_routes`, a **regex** route, and a
+**worker's `-Q`** — which queues a worker actually consumes is a fact about a
+deployment, not the tree.
+
+## Options
+
+```json
+{
+  "context": "shop",
+  "service": "billing",
+  "source": ".",
+  "settings": "config.settings",
+  "out": "celery.json"
+}
+```
+
+`source` is the directory the tasks and their callers are looked for in, the
+input root unless said otherwise. `settings` is only needed where `manage.py`
+does not name the settings module.
+
+## Extraction limits
+
+These cases do not become facts in the fragment, and each is reported:
+
+- a tree with no task in it;
+- a task nothing in the tree enqueues — it is still a `receive`, on the queue
+  its route gives it;
+- an enqueue of a name that does not resolve to a task declared here;
+- a task sent by name that no function here declares — a `send` with no
+  handler, and no flow;
+- a `task_routes` pattern that matches no task;
+- `task_routes` that is not a literal mapping;
+- a settings module named and not found;
+- a file that does not parse, by path.
+
+## Manifest
+
+```json
+{
+  "plugins": [{ "name": "celery", "process": { "command": "python3", "args": ["plugins/extract-celery/main.py"] } }],
+  "extract": [
+    {
+      "plugin": "celery",
+      "in": "examples/shop/billing",
+      "out": "examples/shop/billing/portolan",
+      "options": { "context": "shop", "service": "billing", "out": "celery.json" }
+    }
+  ]
+}
+```
+
+## Tests
+
+```bash
+python3 -m unittest discover -s plugins/extract-celery -t plugins/extract-celery -p "*_test.py"
+```
+
+The reader is held to fixtures under `testdata/`: `billing`, a Django project
+with each shape this reads present once — the three ways a queue is chosen,
+`on_commit` in both forms, a signature, a countdown — against the golden
+`expected.json`; and `drift`, a tree where every diagnostic the reader is
+meant to raise is raised once. `UPDATE_GOLDEN=1` writes the goldens again
+after a deliberate change, and the diff is the review.

package/plugins/extract-celery/extract.py

@@ -0,0 +1,346 @@
+"""A tree with Celery in it in, one fragment out: the work queues the service
+sends on and works from, and one flow per task that is both enqueued and
+declared here.
+
+A fragment, not a catalog: it carries one context and one service with
+nothing on it but channels, and is merged with what the domain extractor said
+about the same service before anything validates it. A task is not a domain
+event and is not written as one; the queue is a channel of kind `job`, which
+is what lets many callers enqueue the same task without the merge calling
+them rival publishers.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+import catalog
+import celery_conf as conf
+import celery_conf as routes
+from names import slug, title
+from options import Options
+from producers import Producer, read_producers, resolve
+from protocol import Builder, File, Input
+from source import Project
+from celery_tasks import Task, index, read_tasks
+
+JOB = "job"
+
+
+class Queue:
+    """One queue as the fragment sees it: the tasks sent on it and the tasks
+    worked from it."""
+
+    def __init__(self, address: str):
+        self.address = address
+        self.sends: Dict[str, List[Producer]] = {}  # wire name -> its producers, in path order
+        self.works: Dict[str, Task] = {}  # wire name -> the task declared here
+        self.how: Dict[str, str] = {}  # wire name -> which rule routed it
+        self.schedules: Dict[str, List[conf.Schedule]] = {}  # wire name -> what the clock sets off
+
+
+def extract(input_: Input, opts: Options, b: Builder, cwd: str = "") -> None:
+    cwd = cwd or os.getcwd()
+    root = os.path.abspath(os.path.join(cwd, input_.root))
+
+    def rel(path: str) -> str:
+        return os.path.relpath(path, cwd).replace(os.sep, "/")
+
+    source = os.path.normpath(os.path.join(root, opts.source or "."))
+    context = opts.context or os.path.basename(root)
+    service = opts.service or os.path.basename(root)
+    svc_id = context + "." + service
+
+    project = Project(root, source, rel)
+    for path, message in project.broken:
+        b.warn(path, "cannot be parsed, so nothing in it is read: %s" % message)
+
+    tasks = read_tasks(project)
+    if not tasks:
+        b.warn(svc_id, "no Celery tasks under %s: a function decorated @shared_task or @app.task is what this reads" % rel(source))
+    by_key, by_name = index(tasks)
+
+    cfg = conf.read_config(project, opts.settings)
+    if cfg.settings and not cfg.settings_found:
+        b.warn(svc_id, "settings module `%s` not found: only what the app module configures itself is read, and a task nothing places lands on `%s`" % (cfg.settings, conf.DEFAULT_QUEUE))
+    elif not cfg.settings and not cfg.apps:
+        b.warn(svc_id, "no Celery app and no settings module found, so a task with no queue of its own lands on `%s`" % conf.DEFAULT_QUEUE)
+    for where in cfg.opaque:
+        b.warn(where, "task_routes is not a literal mapping, so the routes are not read: this reader does not run a router")
+    for pattern in routes.unmatched(cfg, [task.name for task in tasks]):
+        b.warn(svc_id, "task_routes pattern `%s` matches no task in this tree" % pattern)
+
+    queues: Dict[str, Queue] = {}
+
+    def queue(address: str) -> Queue:
+        if address not in queues:
+            queues[address] = Queue(address)
+        return queues[address]
+
+    enqueued = set()
+    for producer in read_producers(project):
+        task: Optional[Task] = None
+        if producer.wire:
+            task = by_name.get(producer.wire)
+            wire = producer.wire
+        else:
+            task = by_key.get(producer.key) if producer.key else None
+            if task is None:
+                # An unresolved name that only one task answers to is that task.
+                same = [t for t in tasks if t.short == producer.label]
+                task = same[0] if len(same) == 1 else None
+            if task is None:
+                b.warn(producer.line, "`%s` is enqueued, but does not resolve to a task declared in this tree" % producer.label)
+                continue
+            wire = task.name
+        address, how = routes.queue_for(wire, producer.queue, task.queue if task else "", cfg)
+        q = queue(address)
+        q.sends.setdefault(wire, []).append(producer)
+        q.how.setdefault(wire, how)
+        if task is not None:
+            q.works[wire] = task
+            enqueued.add(task.key)
+        else:
+            b.warn(producer.line, "`%s` is sent as a task no function in this tree declares; recorded as a send with no handler here" % wire)
+
+    # Beat is one more producer: the clock enqueues the task, and the entry
+    # says which task, when, and on which queue.
+    if cfg.beat_in_database:
+        b.warn(svc_id, "%s is installed, so the schedules live in the database and are not read from this tree" % conf.BEAT_IN_DATABASE)
+    for where in cfg.opaque_schedules:
+        b.warn(where, "beat_schedule is not a literal mapping of entries, so what the clock sets off is not read")
+    for entry in cfg.schedules:
+        task = by_name.get(entry.task) if entry.task else None
+        if task is None and entry.ref:
+            key = resolve(project, entry.module, entry.ref)
+            task = by_key.get(key) if key else None
+            if task is None:
+                same = [t for t in tasks if t.short == entry.ref.split(".")[-1]]
+                task = same[0] if len(same) == 1 else None
+        if task is None:
+            b.warn(entry.where, "beat entry `%s` schedules `%s`, which no task in this tree declares" % (entry.name, entry.task or entry.ref))
+            continue
+        if entry.opaque:
+            b.warn(entry.where, "beat entry `%s` has a schedule this reader cannot read as syntax: `%s`" % (entry.name, entry.when))
+        address, how = routes.queue_for(task.name, entry.queue, task.queue, cfg)
+        q = queue(address)
+        q.works[task.name] = task
+        q.how.setdefault(task.name, how)
+        q.schedules.setdefault(task.name, []).append(entry)
+        enqueued.add(task.key)
+
+    for task in tasks:
+        if task.key in enqueued:
+            continue
+        b.warn(task.line, "task `%s` is declared, but nothing in this tree enqueues it" % task.name)
+        address, how = routes.queue_for(task.name, "", task.queue, cfg)
+        q = queue(address)
+        q.works[task.name] = task
+        q.how.setdefault(task.name, how)
+
+    channels = [channel_of(queues[address], cfg) for address in sorted(queues)]
+    flows = []
+    for address in sorted(queues):
+        q = queues[address]
+        for wire in sorted(set(q.sends) | set(q.schedules)):
+            task = q.works.get(wire)
+            if task is None:
+                continue
+            if wire in q.sends:
+                flows.append(flow_of(svc_id, context, service, q, wire, task, queues))
+            if wire in q.schedules:
+                flows.append(beat_flow_of(svc_id, context, service, q, wire, task, queues))
+    flows.sort(key=lambda f: f["slug"])
+
+    fragment: Dict[str, Any] = {
+        "generatedAt": input_.generated_at,
+        "commit": input_.commit,
+        "contexts": [
+            {
+                "id": context,
+                "slug": context,
+                "name": "",
+                "summary": "",
+                "services": [
+                    {
+                        "id": svc_id,
+                        "slug": service,
+                        "name": "",
+                        "repo": "",
+                        "path": "",
+                        "readme": "",
+                        "provides": [],
+                        "consumes": [],
+                        "aggregates": [],
+                        "channels": channels,
+                    }
+                ],
+            }
+        ],
+        "defs": {},
+        "flows": flows,
+        "adrs": [],
+    }
+    b.files.append(File(name=opts.out or "celery.json", contents=json.dumps(fragment, indent=2, ensure_ascii=False) + "\n"))
+
+
+def channel_of(q: Queue, cfg: conf.Config) -> Dict[str, Any]:
+    messages = []
+    source = ""
+    for wire in sorted(set(q.sends) | set(q.works)):
+        task = q.works.get(wire)
+        producers = q.sends.get(wire, [])
+        schedules = q.schedules.get(wire, [])
+        doc = task.doc if task else ""
+        if producers:
+            messages.append(catalog.message(wire, task.short if task else wire, doc, "send"))
+            source = source or producers[0].line
+        elif schedules:
+            messages.append(catalog.message(wire, task.short if task else wire, ("Sent by Celery beat, %s. " % when_of(schedules) + doc).strip(), "send"))
+            source = source or schedules[0].where
+        if task:
+            handled = "Worked by `%s`, %s." % (task.short, q.how[wire])
+            if schedules:
+                handled += " Set off by Celery beat, %s." % when_of(schedules)
+            if not producers and not schedules:
+                handled += " Nothing in this tree enqueues it."
+            messages.append(catalog.message(wire, task.short, (handled + " " + doc).strip(), "receive"))
+            source = source or task.line
+    doc = "Tasks enqueued and worked through Celery"
+    doc += " over %s." % cfg.broker_scheme if cfg.broker_scheme else "."
+    return catalog.channel(q.address, JOB, "Celery · " + q.address, doc, messages, source)
+
+
+def flow_of(svc_id: str, context: str, service: str, q: Queue, wire: str, task: Task, queues: Dict[str, Queue]) -> Dict[str, Any]:
+    slugged = slug(service + "-celery-" + task.short)
+    # The same task sent on two queues is two flows, told apart by the queue.
+    if sum(1 for other in queues.values() if wire in other.sends and wire in other.works) > 1:
+        slugged += "-" + slug(q.address)
+    # No dot in the id: a participant is a root of the model, and a dotted id
+    # would read as something nested under a `celery` nobody declared.
+    broker = "celery-" + slug(q.address)
+    producers = q.sends[wire]
+    first = producers[0]
+    notes = list(first.notes)
+    enqueue_note = ("Enqueued " + ", ".join(notes) + ". " if notes else "") + task.doc
+    if len(producers) > 1:
+        enqueue_note = (enqueue_note + " Also enqueued at %s." % ", ".join(p.line for p in producers[1:])).strip()
+
+    def handoff(direction: str) -> Dict[str, str]:
+        return {
+            "kind": "job",
+            "transport": "celery",
+            "channel": q.address,
+            "message": wire,
+            "direction": direction,
+        }
+    return catalog.flow(
+        "flow." + slugged,
+        slugged,
+        title(task.short) + " task",
+        "Celery task `%s` is enqueued on `%s` and worked by `%s`." % (wire, q.address, task.short),
+        first.module.rel,
+        context,
+        [
+            catalog.participant(svc_id, "service", context),
+            catalog.participant(broker, "broker", None, "Celery · " + q.address),
+        ],
+        [
+            catalog.step(
+                "enqueue",
+                svc_id,
+                broker,
+                "call",
+                "enqueue " + task.short,
+                catalog.DECLARED,
+                note=enqueue_note.strip(),
+                line=first.line,
+                handoff=handoff("send"),
+            ),
+            catalog.step(
+                "work",
+                broker,
+                svc_id,
+                "call",
+                task.short,
+                catalog.DECLARED,
+                note="Celery hands `%s` to the worker consuming `%s`, %s." % (wire, q.address, q.how[wire]),
+                line=task.line,
+                continues_at=task.entrypoint,
+                handoff=handoff("receive"),
+            ),
+        ],
+        trigger={"kind": "job", "label": "Celery · " + q.address, "confidence": "high"},
+    )
+
+
+def when_of(schedules: List[conf.Schedule]) -> str:
+    """`cron 0 9 * * * (remind-unpaid-invoices)`, one per entry."""
+    return ", ".join("%s (`%s`)" % (entry.when, entry.name) for entry in schedules)
+
+
+def beat_flow_of(svc_id: str, context: str, service: str, q: Queue, wire: str, task: Task, queues: Dict[str, Queue]) -> Dict[str, Any]:
+    """The flow the clock opens: beat enqueues the task, and the worker runs
+    it. A task the code also enqueues keeps that flow and gets this one beside
+    it, told apart by `-beat`, because what happens when the clock fires and
+    what happens when a request does are two different questions."""
+    slugged = slug(service + "-celery-" + task.short)
+    if any(wire in other.sends for other in queues.values()):
+        slugged += "-beat"
+    if sum(1 for other in queues.values() if wire in other.schedules and wire in other.works) > 1:
+        slugged += "-" + slug(q.address)
+    broker = "celery-" + slug(q.address)
+    schedules = q.schedules[wire]
+    first = schedules[0]
+
+    def handoff(direction: str) -> Dict[str, str]:
+        return {
+            "kind": "job",
+            "transport": "celery",
+            "channel": q.address,
+            "message": wire,
+            "direction": direction,
+        }
+
+    enqueue_note = "Scheduled %s. " % when_of(schedules) + task.doc
+    return catalog.flow(
+        "flow." + slugged,
+        slugged,
+        title(task.short) + " task, on schedule",
+        "Celery beat enqueues `%s` on `%s` %s, and `%s` works it." % (wire, q.address, ", ".join(e.when for e in schedules), task.short),
+        first.module.rel,
+        context,
+        [
+            catalog.participant("celery-beat", "actor", None, "Celery beat"),
+            catalog.participant(svc_id, "service", context),
+            catalog.participant(broker, "broker", None, "Celery · " + q.address),
+        ],
+        [
+            catalog.step(
+                "enqueue",
+                "celery-beat",
+                broker,
+                "call",
+                "enqueue " + task.short,
+                catalog.DECLARED,
+                note=enqueue_note.strip(),
+                line=first.where,
+                handoff=handoff("send"),
+            ),
+            catalog.step(
+                "work",
+                broker,
+                svc_id,
+                "call",
+                task.short,
+                catalog.DECLARED,
+                note="Celery hands `%s` to the worker consuming `%s`, %s." % (wire, q.address, q.how[wire]),
+                line=task.line,
+                continues_at=task.entrypoint,
+                handoff=handoff("receive"),
+            ),
+        ],
+        trigger={"kind": "scheduled", "label": ", ".join(e.when for e in schedules), "confidence": "high"},
+    )