[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F57WZ2RSP5NECGV9XS5AYN":3,"skill-same:01M7F57WZ2RSP5NECGV9XS5AYN":43},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7F57WZ2RSP5NECGV9XS5AYN","queue",null,"How work runs in the background: a job type, putting a job on the queue through a gateway, a worker that runs it through a queue handler, retries, and testing with miniredis.","workflowaiorg\u002Fworkflow","workflowaiorg","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F344728430?v=4","01M7F5606QN4BXN2KJNCJPCKAZ","01M7F5607RE7Y5NNRN60FW9NJ3",0,"MIT","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Fcomponent\u002Fbackend\u002Fqueue\u002Fbase\u002Fskills\u002Fqueue\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: queue\ndescription: \"How work runs in the background: a job type, putting a job on the queue through a gateway, a worker that runs it through a queue handler, retries, and testing with miniredis.\"\n---\n\n# Skill: Queue\n\nWork too slow to do while someone waits runs in the background. A service puts a job on a Redis\nstream, and a worker, in that service or another, runs it. `pkg\u002Fqueue` does the stream work; a\nservice never calls Redis itself.\n\n## When this skill applies\n\n- Adding a job: work a request starts but should not wait for\n- Putting a job on the queue, or running one in a worker\n- Changing what happens when a job fails\n- Testing a job's worker or the code that enqueues it\n\n## How a job runs\n\n`queue.Work` reads one stream until the service stops. For each job it calls the function it was\ngiven, with a `ctx` that ends after `queue.RunFor` (50 seconds), then:\n\n| The function | The job |\n|---|---|\n| returns `nil` | is deleted from the stream |\n| returns an error or panics, or the service stops first | runs again after `queue.RetryAfter` (a minute), in this worker or another |\n| has failed `queue.MaxRuns` (5) times | is dropped, with an error logged |\n\nA job that cannot be read as the job type is dropped at once, with an error logged.\n\n- **A job may run more than once**: again after any failure, and after a worker stopped half-way.\n  Running it again must do no harm. Check whether the work is already done before doing it, or\n  make the write one that can repeat, such as an upsert.\n- **A job finishes within `RunFor`**, and stops when its `ctx` ends. One that goes on past\n  `RetryAfter` is handed to a second worker while the first still runs it. Work that takes longer\n  is split into jobs that each enqueue the next.\n- A job's error is logged as a warning by `Work`; the function does not log it again.\n\n## A job type: `pkg\u002Fjobs\u002F\u003Cverb>_\u003Cnoun>.go`\n\nThe job is a struct with `json` tags, and its stream is a constant beside it. It is in the root\n`pkg\u002F` because the service that enqueues it and the one that runs it both import it.\n\n```go\npackage jobs\n\n\u002F\u002F SendReceiptStream is the stream of SendReceipt jobs.\nconst SendReceiptStream = \"orders:send-receipt\"\n\n\u002F\u002F SendReceipt mails the receipt of a paid order.\ntype SendReceipt struct {\n    OrderID int64 `json:\"order_id\"`\n}\n```\n\n- The name says the action, `SendReceipt`, not the thing, `Receipt`.\n- The stream is `\u003Cservice>:\u003Caction>`, after the service that owns the work.\n- The job carries IDs, not copies of rows: by the time it runs, the row may have changed.\n- A field added later is read as its zero value from jobs already waiting; a field renamed or\n  removed is lost from them.\n\n## Enqueuing: a gateway\n\nA controller that starts a job depends on an interface of its own, as for any gateway. The gateway\nis `internal\u002Fgateway\u002F\u003Cdomain>\u002Fqueue\u002F`, and returns an `APIError`, never a Redis error:\n\n```go\nfunc (g *Gateway) SendReceipt(ctx context.Context, orderID int64) error {\n    if err := g.queue.Enqueue(ctx, jobs.SendReceiptStream, jobs.SendReceipt{OrderID: orderID}); err != nil {\n        return errors.New(errors.CodeInternal, \"Could not send the receipt\", err)\n    }\n    return nil\n}\n```\n\nThe route builds it from the `App`: `receiptqueue.New(application.Queue)`.\n\n## Running: a queue handler\n\nA worker is a transport like HTTP: `internal\u002Fhandler\u002F\u003Cdomain>\u002Fqueue\u002F` has one method per job, which\ncalls the controller and returns its error.\n\n```go\nfunc (h *Handler) SendReceipt(ctx context.Context, job jobs.SendReceipt) error {\n    return h.ctrl.SendReceipt(ctx, job.OrderID)\n}\n```\n\nThe route starts it, with the `ctx` `main` passes, which ends when the service is told to stop:\n\n```go\napplication.Workers.Go(func() {\n    queue.Work(ctx, application.Queue, jobs.SendReceiptStream, handler.SendReceipt)\n})\n```\n\n`main` waits for every worker to stop before it closes the queue. A job cut short by the stop runs\nagain later.\n\n## A new service with the queue\n\nCopied from `api`, it already reads `REDIS_ADDR` and has the `Queue` on its `App`. In\n`docker-compose.yaml`, give it `depends_on: redis: condition: service_healthy`, as `api` has.\n\n## Testing\n\n- `pkg\u002Fqueue` is tested against [miniredis](https:\u002F\u002Fgithub.com\u002Falicebob\u002Fminiredis), an in-process\n  Redis: `queue.New(miniredis.RunT(t).Addr())`.\n- The queue handler and the gateway are tested like any other: the handler with a stand-in\n  controller, the gateway against miniredis, reading back what it put on the stream.\n- The controller's work is tested in the controller, with no queue at all.\n\n## Definition of done\n\n- [ ] The job is a struct with `json` tags in `pkg\u002Fjobs\u002F`, named for its action, with its stream\n- [ ] Running a job twice does no harm, and it finishes within `RunFor`\n- [ ] Enqueuing goes through a gateway that returns an `APIError`\n- [ ] The worker is a queue handler that calls the controller, started with `application.Workers.Go`\n- [ ] The handler, the gateway and the controller each have tests\n","# Skill: Queue\n\nWork too slow to do while someone waits runs in the background. A service puts a job on a Redis\nstream, and a worker, in that service or another, runs it. `pkg\u002Fqueue` does the stream work; a\nservice never calls Redis itself.\n\n## When this skill applies\n\n- Adding a job: work a request starts but should not wait for\n- Putting a job on the queue, or running one in a worker\n- Changing what happens when a job fails\n- Testing a job's worker or the code that enqueues it\n\n## How a job runs\n\n`queue.Work` reads one stream until the service stops. For each job it calls the function it was\ngiven, with a `ctx` that ends after `queue.RunFor` (50 seconds), then:\n\n| The function | The job |\n|---|---|\n| returns `nil` | is deleted from the stream |\n| returns an error or panics, or the service stops first | runs again after `queue.RetryAfter` (a minute), in this worker or another |\n| has failed `queue.MaxRuns` (5) times | is dropped, with an error logged |\n\nA job that cannot be read as the job type is dropped at once, with an error logged.\n\n- **A job may run more than once**: again after any failure, and after a worker stopped half-way.\n  Running it again must do no harm. Check whether the work is already done before doing it, or\n  make the write one that can repeat, such as an upsert.\n- **A job finishes within `RunFor`**, and stops when its `ctx` ends. One that goes on past\n  `RetryAfter` is handed to a second worker while the first still runs it. Work that takes longer\n  is split into jobs that each enqueue the next.\n- A job's error is logged as a warning by `Work`; the function does not log it again.\n\n## A job type: `pkg\u002Fjobs\u002F\u003Cverb>_\u003Cnoun>.go`\n\nThe job is a struct with `json` tags, and its stream is a constant beside it. It is in the root\n`pkg\u002F` because the service that enqueues it and the one that runs it both import it.\n\n```go\npackage jobs\n\n\u002F\u002F SendReceiptStream is the stream of SendReceipt jobs.\nconst SendReceiptStream = \"orders:send-receipt\"\n\n\u002F\u002F SendReceipt mails the receipt of a paid order.\ntype SendReceipt struct {\n    OrderID int64 `json:\"order_id\"`\n}\n```\n\n- The name says the action, `SendReceipt`, not the thing, `Receipt`.\n- The stream is `\u003Cservice>:\u003Caction>`, after the service that owns the work.\n- The job carries IDs, not copies of rows: by the time it runs, the row may have changed.\n- A field added later is read as its zero value from jobs already waiting; a field renamed or\n  removed is lost from them.\n\n## Enqueuing: a gateway\n\nA controller that starts a job depends on an interface of its own, as for any gateway. The gateway\nis `internal\u002Fgateway\u002F\u003Cdomain>\u002Fqueue\u002F`, and returns an `APIError`, never a Redis error:\n\n```go\nfunc (g *Gateway) SendReceipt(ctx context.Context, orderID int64) error {\n    if err := g.queue.Enqueue(ctx, jobs.SendReceiptStream, jobs.SendReceipt{OrderID: orderID}); err != nil {\n        return errors.New(errors.CodeInternal, \"Could not send the receipt\", err)\n    }\n    return nil\n}\n```\n\nThe route builds it from the `App`: `receiptqueue.New(application.Queue)`.\n\n## Running: a queue handler\n\nA worker is a transport like HTTP: `internal\u002Fhandler\u002F\u003Cdomain>\u002Fqueue\u002F` has one method per job, which\ncalls the controller and returns its error.\n\n```go\nfunc (h *Handler) SendReceipt(ctx context.Context, job jobs.SendReceipt) error {\n    return h.ctrl.SendReceipt(ctx, job.OrderID)\n}\n```\n\nThe route starts it, with the `ctx` `main` passes, which ends when the service is told to stop:\n\n```go\napplication.Workers.Go(func() {\n    queue.Work(ctx, application.Queue, jobs.SendReceiptStream, handler.SendReceipt)\n})\n```\n\n`main` waits for every worker to stop before it closes the queue. A job cut short by the stop runs\nagain later.\n\n## A new service with the queue\n\nCopied from `api`, it already reads `REDIS_ADDR` and has the `Queue` on its `App`. In\n`docker-compose.yaml`, give it `depends_on: redis: condition: service_healthy`, as `api` has.\n\n## Testing\n\n- `pkg\u002Fqueue` is tested against [miniredis](https:\u002F\u002Fgithub.com\u002Falicebob\u002Fminiredis), an in-process\n  Redis: `queue.New(miniredis.RunT(t).Addr())`.\n- The queue handler and the gateway are tested like any other: the handler with a stand-in\n  controller, the gateway against miniredis, reading back what it put on the stream.\n- The controller's work is tested in the controller, with no queue at all.\n\n## Definition of done\n\n- [ ] The job is a struct with `json` tags in `pkg\u002Fjobs\u002F`, named for its action, with its stream\n- [ ] Running a job twice does no harm, and it finishes within `RunFor`\n- [ ] Enqueuing goes through a gateway that returns an `APIError`\n- [ ] The worker is a queue handler that calls the controller, started with `application.Workers.Go`\n- [ ] The handler, the gateway and the controller each have tests\n",{"name":5,"description":7},"main","68fb57dd74de5ed76dcfaff357932684f77650e6","internal\u002Fcomponent\u002Fbackend\u002Fqueue\u002Fbase\u002Fskills\u002Fqueue","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg","2026-11-13 17:41:05",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add workflowaiorg\u002Fworkflow --skill queue",{"tool":35,"command":36},"bunx","bunx skills add workflowaiorg\u002Fworkflow --skill queue",{"tool":38,"command":39},"pnpm","pnpm dlx skills add workflowaiorg\u002Fworkflow --skill queue","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Fcomponent\u002Fbackend\u002Fqueue\u002Fbase\u002Fskills\u002Fqueue\u002FSKILL.md",true,[],[44,51,58,65,72,77],{"skillNo":45,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":48,"categories":49,"keywords":50,"publishedAt":18},"01M7F58YP2QA8F89599TDWEY0Y","notes","Where notes go.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fnotes\u002FSKILL.md",[],[],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":18},"01M7F58X62078DBFA7YZH0M9VP","naming","How things are named, including the sample's tables.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fnaming\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7F58VXX28G09AJCA667GHBS","local","A skill only this project has.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Flocal\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7F58TQ8XVBD6SDV0S4T6E77","hello","Greets sample's developers.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fhello\u002FSKILL.md",[],[],{"skillNo":73,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":18},"01M7F58R379TW8C6VY572RK11F","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.github\u002Fskills\u002Fnotes\u002FSKILL.md",[],[],{"skillNo":78,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M7F58PNRREJ4KPY496M2XHSY","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.github\u002Fskills\u002Fnaming\u002FSKILL.md",[],[]]