fix(ui): distinguish strict and explicit cache-release counts

Author: strahe

docs/en/concepts/filecoin-storage-flow.md

@@ -56,7 +56,7 @@ If an established provider becomes temporarily unavailable while the initial cop
 
 ## Target and Minimum Replicas
 
-The target replica count is frozen when an upload starts. By default, Release cache after is All replicas (strict): every target replica frozen for that upload must be readable and committed. A bucket can instead set an explicit count from 1 through the current target. An explicit count stays fixed if the target later changes; All replicas follows each upload's frozen target. Once that threshold is met, the version becomes stored and its cache follows the configured eviction policy, while the upload continues filling its original replica slots until the target is reached. The dashboard keeps showing replica sync progress until every frozen target replica is done.
+The target replica count is frozen when an upload starts. By default, **Release cache after** is **All replicas (strict)**: every target replica frozen for that upload must be readable and committed. A bucket can instead set an explicit count from 1 through the current target. An explicit count stays if Replicas later increases; lowering Replicas below that count is rejected until Release cache after is also lowered. **All replicas (strict)** follows each upload's frozen target. Once that threshold is met, the version becomes stored and its cache follows the configured eviction policy, while remaining replicas continue until the upload's target is reached. The dashboard keeps showing replica sync progress until every frozen target replica is done.
 
 Changing the target affects new uploads. Changing the minimum also re-evaluates retained cache for current uploads. Increasing the minimum does not move versions that are already stored back to an earlier state and cannot restore cache that has already been deleted.
 

docs/en/concepts/write-path-cache.md

@@ -42,7 +42,7 @@ Repeated reads of the same version coalesce access-time updates to at most one d
 | `after_upload` | Queue each version for removal after its bucket's minimum durable copies commit. |
 | `none` | Do not create or run automatic cache eviction work. |
 
-Each bucket defaults to strict cache release, so the minimum equals the target replicas frozen for each upload. An operator can set an explicit count from 1 through the current target; that number stays fixed if the target later changes. Lowering the threshold makes retained cache eligible for removal while original replica slots continue syncing. Actual removal still follows `after_upload`, `lru`, or `none`. The minimum is clamped to each upload's target. Raising it affects cache that still exists; it cannot recreate cache that has already been deleted.
+Each bucket defaults to strict cache release, so the minimum equals the target replicas frozen for each upload. In the dashboard, set this on the bucket under Settings → Replica policy. An operator can set an explicit count from 1 through the current target. That count stays if Replicas later increases. Lowering Replicas below the stored count is rejected until Release cache after is also lowered. Lowering the threshold makes retained cache eligible for removal while remaining replicas continue syncing. Actual removal still follows `after_upload`, `lru`, or `none`. The minimum is clamped to each upload's target. Raising it affects cache that still exists; it cannot recreate cache that has already been deleted.
 
 Only versions that currently meet their minimum and have a readable committed remote copy are eligible. Eviction checks the current minimum again before authorizing deletion and waits for active reads of the same version to close. Because cleanup is asynchronous, writes can still return `507 Insufficient Storage` when cleanup cannot keep pace or no safe candidate exists.
 

docs/zh/concepts/filecoin-storage-flow.md

@@ -56,7 +56,7 @@ synaps3 admin task retry 42
 
 ## 目标副本与最低耐久副本
 
-上传开始时会冻结目标副本数。默认情况下，Release cache after 为 All replicas (strict)：该次上传冻结的全部目标副本都必须可读并完成提交。存储桶也可以设置 1 到当前目标之间的显式数量。显式数量在目标随后提高时保持不变；All replicas 会跟随每次上传冻结的目标。达到该门槛后，版本进入已存储状态，缓存按已配置的淘汰策略处理；上传仍会继续补齐原有副本位，直到达到目标副本数。在冻结的目标副本全部完成前，仪表盘会继续显示副本同步进度。
+上传开始时会冻结目标副本数。默认情况下，**Release cache after** 为 **All replicas (strict)**：该次上传冻结的全部目标副本都必须可读并完成提交。存储桶也可以设置 1 到当前目标之间的显式数量。显式数量在目标随后提高时保持不变；如果把 Replicas 降到低于该数量，请求会被拒绝，必须同时降低 Release cache after。**All replicas (strict)** 会跟随每次上传冻结的目标。达到该门槛后，版本进入已存储状态，缓存按已配置的淘汰策略处理；其余副本会继续补齐，直到达到该次上传的目标副本数。在冻结的目标副本全部完成前，仪表盘会继续显示副本同步进度。
 
 修改目标副本数只影响新上传。修改最低耐久副本数也会重新评估当前上传仍保留的缓存。提高门槛不会让已经进入已存储状态的版本回退，也无法恢复已经删除的缓存。
 

docs/zh/concepts/write-path-cache.md

@@ -42,7 +42,7 @@ SynapS3 会校验请求，保存对象及其元数据，再返回 S3 兼容的 E
 | `after_upload` | 存储桶要求的最低耐久副本提交后，为该版本排队清理。 |
 | `none` | 不创建或执行自动缓存淘汰任务。 |
 
-每个存储桶默认采用严格缓存释放策略，因此最低耐久副本数等于每次上传冻结的目标副本数。运维人员可以设置 1 到当前目标之间的显式数量；目标随后提高时该数字保持不变。降低门槛只会让仍保留的缓存有资格被删除，原副本位会继续补齐。是否真正删除仍取决于 `after_upload`、`lru` 或 `none`。该门槛不会超过单次上传的目标副本数。提高门槛只影响尚未删除的缓存，无法恢复已经删除的缓存。
+每个存储桶默认采用严格缓存释放策略，因此最低耐久副本数等于每次上传冻结的目标副本数。在仪表盘中，到该存储桶的 Settings → Replica policy 设置。运维人员可以设置 1 到当前目标之间的显式数量；目标随后提高时该数字保持不变。如果把 Replicas 降到低于已保存的显式数量，请求会被拒绝，必须同时降低 Release cache after。降低门槛只会让仍保留的缓存有资格被删除，其余副本会继续补齐。是否真正删除仍取决于 `after_upload`、`lru` 或 `none`。该门槛不会超过单次上传的目标副本数。提高门槛只影响尚未删除的缓存，无法恢复已经删除的缓存。
 
 只有当前满足最低耐久副本数且存在可读已提交远端副本的版本才可淘汰。系统会在授权删除前再次检查当前门槛，并等待同一版本正在进行的读取关闭。清理是异步流程，因此清理追赶不及时或没有安全候选时，写入仍可能返回 `507 Insufficient Storage`。
 

ui/src/lib/bucket-copy-policy.ts

@@ -24,12 +24,20 @@ export function bucketCopyPolicyInheritOptionLabel(bucket: BucketCopyPolicy, run
   return `Inherit current runtime default (${copyCountLabel(copies)})`
 }
 
+export function replicaTargetChoiceNote() {
+  return 'Applies to new uploads. Existing objects keep the replica target they started with.'
+}
+
 export function bucketCopyPolicySavedMessage() {
-  return 'Replica policy saved.'
+  return 'Saved. New uploads use this replica target. Cache can be released after the selected count.'
 }
 
 export function minimumDurableCopiesChoiceNote() {
-  return 'Waits for every target replica of that upload.'
+  return 'Keeps cache until every replica of that upload is stored, including later Replicas increases.'
+}
+
+export function minimumDurableCopiesFixedCountNote() {
+  return 'Keeps this count if Replicas later increases.'
 }
 
 export function minimumDurableCopiesValue(bucket: Pick<BucketItem, 'minimum_durable_copies' | 'effective_copies'>) {
@@ -43,8 +51,12 @@ export function minimumDurableCopiesLabel(bucket: BucketCopyPolicy) {
   return `${bucket.effective_minimum_durable_copies} of ${bucket.effective_copies} ${bucket.effective_copies === 1 ? 'replica' : 'replicas'}`
 }
 
-export function minimumDurableCopiesOptionLabel(copies: number) {
-  return `${copies} ${copies === 1 ? 'replica' : 'replicas'}`
+export function minimumDurableCopiesOptionLabel(copies: number, targetCopies?: number | null) {
+  const count = `${copies} ${copies === 1 ? 'replica' : 'replicas'}`
+  if (targetCopies != null && copies === targetCopies) {
+    return `${count} (fixed count)`
+  }
+  return count
 }
 
 export function selectedTargetCopies(copyPolicy: string, runtimeDefaultCopies?: number) {

ui/src/routes/buckets.$name.tsx

@@ -122,12 +122,14 @@ import {
   copyPolicyOptions,
   inheritedCopyPolicyValue,
   minimumDurableCopiesChoiceNote,
+  minimumDurableCopiesFixedCountNote,
   minimumDurableCopiesLabel,
   minimumDurableCopiesOptionLabel,
   minimumDurableCopiesOptions,
   minimumDurableCopiesValue,
   minimumDurableCopiesWarning,
   persistMinimumDurableCopies,
+  replicaTargetChoiceNote,
   selectedTargetCopies,
   showsMinimumDurableCopiesWarning,
   strictMinimumDurableCopiesValue,
@@ -2316,6 +2318,7 @@ function BucketDetailsSettings({
                 </SelectGroup>
               </SelectContent>
             </Select>
+            <FieldDescription>{replicaTargetChoiceNote()}</FieldDescription>
           </Field>
           <Field>
             <FieldLabel htmlFor={`bucket-minimum-durable-copies-${bucket.id}`}>Release cache after</FieldLabel>
@@ -2332,14 +2335,16 @@ function BucketDetailsSettings({
                   <SelectItem value={strictMinimumDurableCopiesValue}>All replicas (strict)</SelectItem>
                   {minimumOptions.map((copies) => (
                     <SelectItem key={copies} value={copies.toString()}>
-                      {minimumDurableCopiesOptionLabel(copies)}
+                      {minimumDurableCopiesOptionLabel(copies, targetCopies)}
                     </SelectItem>
                   ))}
                 </SelectGroup>
               </SelectContent>
             </Select>
-            {minimumDurableCopies === strictMinimumDurableCopiesValue && (
+            {minimumDurableCopies === strictMinimumDurableCopiesValue ? (
               <FieldDescription>{minimumDurableCopiesChoiceNote()}</FieldDescription>
+            ) : (
+              <FieldDescription>{minimumDurableCopiesFixedCountNote()}</FieldDescription>
             )}
           </Field>
         </FieldGroup>

ui/src/routes/buckets.index.tsx

@@ -31,10 +31,12 @@ import {
   copyPolicyOptions,
   inheritedCopyPolicyValue,
   minimumDurableCopiesChoiceNote,
+  minimumDurableCopiesFixedCountNote,
   minimumDurableCopiesLabel,
   minimumDurableCopiesOptionLabel,
   minimumDurableCopiesOptions,
   minimumDurableCopiesWarning,
+  replicaTargetChoiceNote,
   selectedTargetCopies,
   showsMinimumDurableCopiesWarning,
   strictMinimumDurableCopiesValue,
@@ -184,11 +186,13 @@ function CreateBucketDialog() {
                   </SelectGroup>
                 </SelectContent>
               </Select>
-              {copyPolicy === inheritedCopyPolicyValue && runtimeDefaultCopies == null && (
+              {copyPolicy === inheritedCopyPolicyValue && runtimeDefaultCopies == null ? (
                 <FieldDescription>
                   The current runtime default is unavailable. Choose a replica count to configure an explicit
                   cache-release threshold.
                 </FieldDescription>
+              ) : (
+                <FieldDescription>{replicaTargetChoiceNote()}</FieldDescription>
               )}
             </Field>
             <Field>
@@ -206,14 +210,16 @@ function CreateBucketDialog() {
                     <SelectItem value={strictMinimumDurableCopiesValue}>All replicas (strict)</SelectItem>
                     {minimumOptions.map((copies) => (
                       <SelectItem key={copies} value={copies.toString()}>
-                        {minimumDurableCopiesOptionLabel(copies)}
+                        {minimumDurableCopiesOptionLabel(copies, targetCopies)}
                       </SelectItem>
                     ))}
                   </SelectGroup>
                 </SelectContent>
               </Select>
-              {minimumDurableCopies === strictMinimumDurableCopiesValue && (
+              {minimumDurableCopies === strictMinimumDurableCopiesValue ? (
                 <FieldDescription>{minimumDurableCopiesChoiceNote()}</FieldDescription>
+              ) : (
+                <FieldDescription>{minimumDurableCopiesFixedCountNote()}</FieldDescription>
               )}
             </Field>
           </FieldGroup>

ui/test/bucket-copy-policy.test.ts

@@ -6,19 +6,36 @@ import {
   bucketCopyPolicySavedMessage,
   clampMinimumDurableCopiesValue,
   minimumDurableCopiesChoiceNote,
+  minimumDurableCopiesFixedCountNote,
   minimumDurableCopiesLabel,
+  minimumDurableCopiesOptionLabel,
   minimumDurableCopiesOptions,
   minimumDurableCopiesValue,
   minimumDurableCopiesWarning,
   persistMinimumDurableCopies,
+  replicaTargetChoiceNote,
   selectedTargetCopies,
   showsMinimumDurableCopiesWarning,
   strictMinimumDurableCopiesValue,
 } from '../src/lib/bucket-copy-policy.ts'
 
 test('bucket copy policy text explains save result and future upload scope', () => {
-  assert.equal(bucketCopyPolicySavedMessage(), 'Replica policy saved.')
-  assert.equal(minimumDurableCopiesChoiceNote(), 'Waits for every target replica of that upload.')
+  assert.equal(
+    replicaTargetChoiceNote(),
+    'Applies to new uploads. Existing objects keep the replica target they started with.'
+  )
+  assert.equal(
+    bucketCopyPolicySavedMessage(),
+    'Saved. New uploads use this replica target. Cache can be released after the selected count.'
+  )
+  assert.equal(
+    minimumDurableCopiesChoiceNote(),
+    'Keeps cache until every replica of that upload is stored, including later Replicas increases.'
+  )
+  assert.equal(minimumDurableCopiesFixedCountNote(), 'Keeps this count if Replicas later increases.')
+  assert.equal(minimumDurableCopiesOptionLabel(3), '3 replicas')
+  assert.equal(minimumDurableCopiesOptionLabel(3, 3), '3 replicas (fixed count)')
+  assert.equal(minimumDurableCopiesOptionLabel(2, 3), '2 replicas')
   assert.equal(
     minimumDurableCopiesWarning(),
     'Cache may be removed before every target replica is ready. Raising this later cannot restore deleted cache.'