docs(tasks): add Cache-Aside task (type 18) - #19
Conversation
Documents the new Cache-Aside (read-through) task type, mirroring the State Store task page format. Adds TR + EN pages, sidebar entry, and index table row (17→18). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reviewer's GuideDocuments the new Cache-AsideTask (task type 18) in both TR and EN docs, wires it into the tasks index and sidebar navigation, and explains its configuration, runtime behavior, and relationship to the existing StateStore task. Sequence diagram for CacheAsideTask read-through behaviorsequenceDiagram
actor Orchestration
participant CacheAsideTaskExecutor
participant CacheAsideTaskInvoker
participant StateStore
participant SourceTaskInvoker
Orchestration->>CacheAsideTaskExecutor: execute CacheAsideTask
CacheAsideTaskExecutor->>CacheAsideTaskInvoker: cacheaside TaskEnvelope
alt [cache read]
CacheAsideTaskInvoker->>StateStore:
StateStore-->>CacheAsideTaskInvoker: cached value
CacheAsideTaskInvoker-->>CacheAsideTaskExecutor: raw cached result
else [cache miss or forceRefresh]
CacheAsideTaskInvoker->>StateStore:
StateStore-->>CacheAsideTaskInvoker: not found
CacheAsideTaskInvoker->>SourceTaskInvoker: sourceTask envelope
SourceTaskInvoker-->>CacheAsideTaskInvoker: raw source result
CacheAsideTaskInvoker->>StateStore:
StateStore-->>CacheAsideTaskInvoker: stored
CacheAsideTaskInvoker-->>CacheAsideTaskExecutor: raw source result
end
CacheAsideTaskExecutor-->>Orchestration: shaped result via sourceMapping OutputHandler
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughAdded comprehensive CacheAsideTask type 18 documentation in English and localized task pages, including configuration, execution semantics, examples, response metadata, and dynamic cache keys. Updated task counts, catalog entries, and sidebar navigation. ChangesCache-Aside Task
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related issues
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for the new Cache-Aside Task (Type 18) in both Turkish and English, updating the task index files and the sidebar configuration accordingly. The review feedback suggests using relative paths instead of absolute paths for internal links in the "Related" section of both documentation files to ensure that Docusaurus localization (i18n) and versioning function correctly without losing the language context.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| - [Tasks Genel Bakış](/docs/components/tasks/) — task türleri ve referans mekanizması | ||
| - [State Store Task](/docs/components/tasks/state-store) — paylaşılan cache primitifi (get/set/delete); aynı `custom:` prefix ve state store |
There was a problem hiding this comment.
Docusaurus üzerinde yerelleştirme (i18n) ve versiyonlama desteğinin sağlıklı çalışabilmesi için mutlak (absolute) yollar yerine göreceli (relative) yolların kullanılması önerilir. Mutlak yollar (/docs/...), İngilizce (/en/docs/...) gibi farklı dillerdeki sayfalardan tıklandığında kullanıcının dil bağlamını kaybetmesine ve varsayılan dile yönlenmesine neden olur.
| - [Tasks Genel Bakış](/docs/components/tasks/) — task türleri ve referans mekanizması | |
| - [State Store Task](/docs/components/tasks/state-store) — paylaşılan cache primitifi (get/set/delete); aynı `custom:` prefix ve state store | |
| - [Tasks Genel Bakış](./) — task türleri ve referans mekanizması | |
| - [State Store Task](./state-store) — paylaşılan cache primitifi (get/set/delete); aynı custom: prefix ve state store |
| - [Tasks Overview](/docs/components/tasks/) — task types and the reference mechanism | ||
| - [State Store Task](/docs/components/tasks/state-store) — the shared caching primitive (get/set/delete); same `custom:` prefix and state store |
There was a problem hiding this comment.
Docusaurus üzerinde yerelleştirme (i18n) ve versiyonlama desteğinin sağlıklı çalışabilmesi için mutlak (absolute) yollar yerine göreceli (relative) yolların kullanılması önerilir. Mutlak yollar (/docs/...), İngilizce (/en/docs/...) gibi farklı dillerdeki sayfalardan tıklandığında kullanıcının dil bağlamını kaybetmesine ve varsayılan dile yönlenmesine neden olur.
| - [Tasks Overview](/docs/components/tasks/) — task types and the reference mechanism | |
| - [State Store Task](/docs/components/tasks/state-store) — the shared caching primitive (get/set/delete); same `custom:` prefix and state store | |
| - [Tasks Overview](./) — task types and the reference mechanism | |
| - [State Store Task](./state-store) — the shared caching primitive (get/set/delete); same custom: prefix and state store |
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/components/tasks/cache-aside.md`:
- Around line 1-4: Add the required frontmatter to both cache-aside
documentation pages: in docs/components/tasks/cache-aside.md, define stable
Turkish id, slug, and sidebar_label values; in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md,
preserve the source id and slug while translating title and sidebar_label.
- Around line 44-55: Add the missing enum reference table for the consistency
field in docs/components/tasks/cache-aside.md (lines 44-55), using Turkish
descriptions, and in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
(lines 44-55), using English descriptions. Document the supported values
Eventual and Strong consistently with the inline field descriptions.
- Around line 134-143: Update the sourceMapping heading and surrounding wording
in docs/components/tasks/cache-aside.md:134-143 and
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md:134-143
to state that mapping shapes the returned value, while the raw result is what
gets cached and mapping runs only on read. Keep both language versions
semantically consistent with the architecture section.
- Around line 105-146: The Turkish examples in
docs/components/tasks/cache-aside.md lines 105-146 and the corresponding English
examples in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
lines 105-146 need links to working examples. Add specific full GitHub links to
the burgan-tech/vnext-example repository for the inline examples on both pages,
using the appropriate language-specific examples while preserving the existing
documentation content.
- Line 50: Align the ttlInSeconds descriptions in
docs/components/tasks/cache-aside.md (line 50) and
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
(line 50) with the State Store contract by removing the claim that 0 means no
expiry and documenting the valid minimum of 1, or explicitly documenting the
cache-aside exception if that behavior is intentional.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9d8f8d6f-94ef-4a82-bac5-ec70448983c0
📒 Files selected for processing (5)
docs/components/tasks/cache-aside.mddocs/components/tasks/index.mdi18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.mdi18n/en/docusaurus-plugin-content-docs/current/components/tasks/index.mdsidebars.ts
| --- | ||
| sidebar_position: 14 | ||
| title: Cache-Aside Task | ||
| description: Bir kaynağın sonucunu read-through (cache-aside) deseni ile cache'leyen task |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Add required metadata to both documentation pages.
Both pages omit required frontmatter metadata.
docs/components/tasks/cache-aside.md#L1-L4: add stable Turkishid,slug, andsidebar_label.i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L1-L4: preserve the sourceid/slugand translatetitle/sidebar_label.
📍 Affects 2 files
docs/components/tasks/cache-aside.md#L1-L4(this comment)i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L1-L4
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components/tasks/cache-aside.md` around lines 1 - 4, Add the required
frontmatter to both cache-aside documentation pages: in
docs/components/tasks/cache-aside.md, define stable Turkish id, slug, and
sidebar_label values; in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md,
preserve the source id and slug while translating title and sidebar_label.
Source: Coding guidelines
| ## Konfigürasyon Alanları | ||
|
|
||
| | Alan | Tip | Zorunlu | Açıklama | | ||
| |------|-----|---------|----------| | ||
| | `key` | string | Evet* | Cache anahtarı; **verbatim** kullanılır. Dinamik anahtar için transition mapping'inin `InputHandler`'ı `task.SetCacheKey(...)` çağırır (State Store task'ındaki standart mekanizmanın aynısı). *Statik `key` yoksa anahtar mapping ile set edilmelidir | | ||
| | `storeName` | string | Hayır | Cache olarak kullanılacak Dapr state store bileşen adı. Boş bırakılırsa çalışan runtime'ın `DAPR_STATE_STORE_NAME` konfigürasyon değeri kullanılır | | ||
| | `ttlInSeconds` | integer | Hayır | Cache kaydının time-to-live süresi (Dapr `ttlInSeconds` metadata'sı). Belirtilmezse veya `0` ise kayıt **süresizdir** | | ||
| | `consistency` | string | Hayır | `Eventual` (varsayılan) veya `Strong` — okuma ve yazmada state store'a geçirilir | | ||
| | `sourceTask` | object | Evet | Cache miss'te çalıştırılan task referansı (`key` / `domain` / `flow` / `version`). **Uzaktan invoke edilebilir** bir tip olmalıdır (HTTP / SOAP / Dapr / GetInstanceData). `flow` verilmezse runtime tasks şeması varsayılır | | ||
| | `sourceMapping` | object | Hayır | Cache'lenmiş (ham) sonucu döndürmeden önce şekillendiren `.csx` mapping (`location` + base64 `code`). Mapping'in `OutputHandler`'ı olarak, hem hit hem miss durumunda **okuma anında** çalışır | | ||
| | `bypassOnCacheError` | boolean | Hayır | `true` (varsayılan): cache okuma/yazma hataları pipeline'ı düşürmek yerine source task'a fallback yapar. `false`: cache hataları task başarısızlığı olarak yüzeye çıkar (error boundary uygulanır) | | ||
| | `forceRefresh` | boolean | Hayır | `true`: cache okuma atlanır; source task her zaman çalıştırılır ve kayıt üzerine yazılır | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Complete the component reference template.
Both pages document the fixed consistency values inline but omit the required enum table.
docs/components/tasks/cache-aside.md#L44-L55: add the Turkish enum table.i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L44-L55: add the English enum table.
📍 Affects 2 files
docs/components/tasks/cache-aside.md#L44-L55(this comment)i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L44-L55
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components/tasks/cache-aside.md` around lines 44 - 55, Add the missing
enum reference table for the consistency field in
docs/components/tasks/cache-aside.md (lines 44-55), using Turkish descriptions,
and in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
(lines 44-55), using English descriptions. Document the supported values
Eventual and Strong consistently with the inline field descriptions.
Source: Coding guidelines
| |------|-----|---------|----------| | ||
| | `key` | string | Evet* | Cache anahtarı; **verbatim** kullanılır. Dinamik anahtar için transition mapping'inin `InputHandler`'ı `task.SetCacheKey(...)` çağırır (State Store task'ındaki standart mekanizmanın aynısı). *Statik `key` yoksa anahtar mapping ile set edilmelidir | | ||
| | `storeName` | string | Hayır | Cache olarak kullanılacak Dapr state store bileşen adı. Boş bırakılırsa çalışan runtime'ın `DAPR_STATE_STORE_NAME` konfigürasyon değeri kullanılır | | ||
| | `ttlInSeconds` | integer | Hayır | Cache kaydının time-to-live süresi (Dapr `ttlInSeconds` metadata'sı). Belirtilmezse veya `0` ise kayıt **süresizdir** | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'FILES:\n'
git ls-files | rg '(^|/)(docs/components/tasks/cache-aside\.md|i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside\.md|.*state.*store.*|.*ttlInSeconds.*|.*cache-aside.*)$' || true
printf '\nSEARCH ttlInSeconds:\n'
rg -n --hidden --glob '!**/node_modules/**' 'ttlInSeconds|TTL|Time-to-live|state store|State Store' docs i18n . 2>/dev/null | sed -n '1,240p'Repository: burgan-tech/vnext-docs
Length of output: 30286
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'CACHE-ASIDE (TR/EN) TTL SECTION:\n'
sed -n '40,60p' docs/components/tasks/cache-aside.md
printf '\n---\n'
sed -n '40,60p' i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
printf '\nSTATE-STORE (TR/EN) TTL SECTION:\n'
sed -n '40,58p' docs/components/tasks/state-store.md
printf '\n---\n'
sed -n '40,58p' i18n/en/docusaurus-plugin-content-docs/current/components/tasks/state-store.mdRepository: burgan-tech/vnext-docs
Length of output: 6488
🌐 Web query:
Dapr state store ttlInSeconds 0 no expiry minimum 1 documentation
💡 Result:
In Dapr, the behavior of ttlInSeconds regarding expiration and persistence is as follows: 1. To indicate that a specific state record should never expire (persist indefinitely) and to ignore any default TTL policies (whether set globally in the Dapr component or at the database level), you should set ttlInSeconds to -1 [1][2]. 2. When ttlInSeconds is set to 0, it typically does not signify "no expiry." Instead, for many Dapr state store components, setting ttlInSeconds to a value of 0 or less as a global default in the component configuration means that no default TTL is applied [3]. In this scenario, items will only expire if a TTL is explicitly provided in the request metadata [3]. In summary, use -1 to explicitly persist data indefinitely [1], while 0 is generally used to disable the application of a default TTL policy [3]. Always verify the specific behavior for your chosen state store component, as support for TTL features can vary between implementations [1][4].
Citations:
- 1: https://docs.dapr.io/developing-applications/building-blocks/state-management/state-store-ttl/
- 2: https://v1-14.docs.dapr.io/developing-applications/building-blocks/state-management/state-store-ttl/
- 3: https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-dynamodb/
- 4: https://docs.dapr.io/reference/api/state_api/
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'TTL VALIDATION / TASK IMPLEMENTATION SEARCH:\n'
rg -n --hidden --glob '!**/node_modules/**' 'ttlInSeconds|minimum: 1|no expiry|never expire|CacheAsideTask|StateStoreTask|SetCacheKey|IStateStoreClient' . 2>/dev/null | sed -n '1,260p'Repository: burgan-tech/vnext-docs
Length of output: 8948
Align ttlInSeconds semantics across both cache-aside docs. docs/components/tasks/cache-aside.md and its English mirror say 0 means no expiry, but the State Store task already documents ttlInSeconds as minimum: 1. Make the cache-aside wording match that contract, or call out an explicit exception.
📍 Affects 2 files
docs/components/tasks/cache-aside.md#L50-L50(this comment)i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L50-L50
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components/tasks/cache-aside.md` at line 50, Align the ttlInSeconds
descriptions in docs/components/tasks/cache-aside.md (line 50) and
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
(line 50) with the State Store contract by removing the claim that 0 means no
expiry and documenting the valid minimum of 1, or explicitly documenting the
cache-aside exception if that behavior is intentional.
| ## Örnekler | ||
|
|
||
| ### Basit read-through (HTTP source) | ||
|
|
||
| ```json | ||
| "attributes": { | ||
| "type": "18", | ||
| "config": { | ||
| "key": "customer:42:profile", | ||
| "storeName": "vnext-state", | ||
| "ttlInSeconds": 300, | ||
| "sourceTask": { "key": "get-customer-http", "domain": "core", "flow": "sys-tasks", "version": "1.0.0" } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### `forceRefresh` — cache'i her zaman tazele | ||
|
|
||
| ```json | ||
| "attributes": { | ||
| "type": "18", | ||
| "config": { | ||
| "key": "customer:42:profile", | ||
| "sourceTask": { "key": "get-customer-http", "domain": "core", "flow": "sys-tasks", "version": "1.0.0" }, | ||
| "forceRefresh": true | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### `sourceMapping` — ham sonucu şekillendirerek cache'le/dön | ||
|
|
||
| ```json | ||
| "attributes": { | ||
| "type": "18", | ||
| "config": { | ||
| "key": "customer:42:profile", | ||
| "sourceTask": { "key": "get-customer-http", "domain": "core", "flow": "sys-tasks", "version": "1.0.0" }, | ||
| "sourceMapping": { "location": "./src/mappings/get-customer-cached.csx", "code": "<base64>" }, | ||
| "ttlInSeconds": 300 | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Add working-example links to both pages.
The inline examples need specific full GitHub links to burgan-tech/vnext-example.
docs/components/tasks/cache-aside.md#L105-L146: link the Turkish examples.i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L105-L146: link the English examples.
🧰 Tools
🪛 LanguageTool
[grammar] ~105-~105: Ensure spelling is correct
Context: ...e ile invalidation yapılabilir. ::: ## Örnekler ### Basit read-through (HTTP source) ```jso...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~134-~134: Ensure spelling is correct
Context: ...ue } } ### `sourceMapping` — ham sonucu şekillendirerek cache'le/dön json "...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
📍 Affects 2 files
docs/components/tasks/cache-aside.md#L105-L146(this comment)i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L105-L146
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components/tasks/cache-aside.md` around lines 105 - 146, The Turkish
examples in docs/components/tasks/cache-aside.md lines 105-146 and the
corresponding English examples in
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md
lines 105-146 need links to working examples. Add specific full GitHub links to
the burgan-tech/vnext-example repository for the inline examples on both pages,
using the appropriate language-specific examples while preserving the existing
documentation content.
Source: Coding guidelines
| ### `sourceMapping` — ham sonucu şekillendirerek cache'le/dön | ||
|
|
||
| ```json | ||
| "attributes": { | ||
| "type": "18", | ||
| "config": { | ||
| "key": "customer:42:profile", | ||
| "sourceTask": { "key": "get-customer-http", "domain": "core", "flow": "sys-tasks", "version": "1.0.0" }, | ||
| "sourceMapping": { "location": "./src/mappings/get-customer-cached.csx", "code": "<base64>" }, | ||
| "ttlInSeconds": 300 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Make sourceMapping semantics consistent with the architecture section.
Both headings imply the mapped value is cached, while the surrounding contract says raw results are cached and mapping runs only on read.
docs/components/tasks/cache-aside.md#L134-L143: state that mapping shapes the returned value, not the cached value.i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L134-L143: make the same correction in English.
🧰 Tools
🪛 LanguageTool
[grammar] ~134-~134: Ensure spelling is correct
Context: ...ue } } ### `sourceMapping` — ham sonucu şekillendirerek cache'le/dön json "...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
📍 Affects 2 files
docs/components/tasks/cache-aside.md#L134-L143(this comment)i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md#L134-L143
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components/tasks/cache-aside.md` around lines 134 - 143, Update the
sourceMapping heading and surrounding wording in
docs/components/tasks/cache-aside.md:134-143 and
i18n/en/docusaurus-plugin-content-docs/current/components/tasks/cache-aside.md:134-143
to state that mapping shapes the returned value, while the raw result is what
gets cached and mapping runs only on read. Keep both language versions
semantically consistent with the architecture section.
Özet
Yeni Cache-Aside (read-through) task'ını (TaskType
18) belgeler. State Store (type 17) task sayfasıyla birebir aynı format/bölümlerde.vnext runtime tarafındaki implementasyon: burgan-tech/vnext PR #814 (
sprint15-26/CacheAside).Değişiklikler
docs/components/tasks/cache-aside.md— yeni (TR)i18n/en/.../components/tasks/cache-aside.md— yeni (EN)sidebars.ts— State Store'dan sonracache-asidegirişidocs/components/tasks/index.md(TR) + EN index — task sayısı 17→18, yeni satırİçerik
Read-through akışı (hit → cached dön, miss → sourceTask çalıştır → sourceMapping ile şekillendir → TTL+consistency ile cache'le), config alanları (key, storeName, ttlInSeconds, consistency, sourceTask, sourceMapping, bypassOnCacheError, forceRefresh), mimari (cache I/O Execution
cacheasideinvoker'ında, StateStore ile ortakcustom:prefix), dinamik anahtar (mapping InputHandler →task.SetCacheKey), örnekler ve standart yanıt.🤖 Generated with Claude Code
Summary by Sourcery
Document the new Cache-Aside Task (type 18) and add it to the task type listings and sidebar navigation.
Documentation:
Summary by CodeRabbit