# Import Into TiKV Capacity Reservation Switch

## Analysis

| Area | Files | Change | Verification | Success criteria |
| --- | --- | --- | --- | --- |
| FeaturesAllowList switch | `internal/model/feature/allowlist.go` | Add `premium-import-into-tikv-reservation` for `featuresSwitchersConfig.featuresAllowList` | `go test ./internal/model/import -run '^(TestImportIntoTiKVCapacityReservationEnabled|TestApplyImportIntoFileDiscoverySourceSize)$' -count=1` | Missing allowlist entry keeps the feature disabled |
| Preparing flow | `internal/model/import/import_into.go` | Gate estimate-size and capacity reservation creation behind the switch | `go test ./internal/model/import -run '^(TestApplyImportIntoFileDiscoverySourceSize|TestReservedImportIntoTiKVBytes)$' -count=1` | Disabled path derives `TotalSize` and `ExecutedNodes` from file discovery and does not require estimate-size |
| Scaling/release flow | `internal/model/import/import_into.go` | Skip TiKV reservation get/delete when the switch is disabled | `go test ./internal/model/import -run '^(TestImportIntoTiKVCapacityReservationEnabled|TestShouldReleaseImportIntoReservationOnFailureStatus)$' -count=1` | Default-off deployments do not call reservation APIs |

## Symbols To Keep

- `prepareImportIntoEstimate`
- `CreateTiKVCapacityReservation`
- `GetTiKVCapacityReservation`
- `DeleteTiKVCapacityReservation`
- Existing async prepare task IDs and failure semantics

## Symbols To Add

- `feature.ImportIntoTiKVReservation`
- `isImportIntoTiKVCapacityReservationEnabled`
- source-size application helper for the disabled path

## Execution Steps

1. Add the FeaturesAllowList feature name for TiKV capacity reservation.
   - Verify with a focused unit test that a missing allowlist entry is disabled.

2. Add helper logic in `internal/model/import/import_into.go`.
   - The enabled helper reads `featuresSwitchersConfig.featuresAllowList`.
   - The disabled-path size helper sums file discovery sizes from pending subtasks and applies the existing DXF node-count calculation.
   - Expected output: pending subtasks receive a stable `ExecutedNodes`; empty data fails with the existing `"import data is empty"` message.

3. Gate the worker state machine.
   - In `onImportIntoPreparing`, use the existing estimate + create reservation path only when enabled.
   - When disabled, apply file discovery source size and move to `ScalingUp`.
   - In `onImportIntoScalingUp`, poll reservation readiness only when enabled.
   - In release cleanup, return immediately when disabled.

4. Run verification.
   - Focused: `go test ./internal/model/import -run '^(TestImportIntoTiKVCapacityReservationEnabled|TestApplyImportIntoFileDiscoverySourceSize|TestShouldReleaseImportIntoReservationOnFailureStatus|TestReservedImportIntoTiKVBytes)$' -count=1`
   - Required after Go code changes: `make app-unit-test-local`

## Oneconfig Example

The switch reuses `server.featuresSwitchersConfig.featuresAllowList` with feature key
`premium-import-into-tikv-reservation`.

Current implementation passes tenant, project, and cluster IDs only. Do not configure
`deploymentMatcher` for this feature unless the worker is later changed to pass
`cluster.RegionName` and `cluster.InfraProviderType` into the feature check; with the
current empty region/provider values, a deployment matcher will make the feature miss.

Enable by tenant:

```yaml
server:
  featuresSwitchersConfig:
    featuresAllowList:
      premium-import-into-tikv-reservation:
        tenantID:
          - "123456789"
```

Enable by project:

```yaml
server:
  featuresSwitchersConfig:
    featuresAllowList:
      premium-import-into-tikv-reservation:
        projectID:
          - "234567890"
```

Enable by cluster:

```yaml
server:
  featuresSwitchersConfig:
    featuresAllowList:
      premium-import-into-tikv-reservation:
        clusterID:
          - "345678901"
```

## Risk Assessment

- If the switch is turned off while an already-created reservation is in flight, release calls are also skipped by design. Operators should drain or leave the switch enabled until in-flight reservation-backed imports finish before disabling it.
- The disabled path uses file discovery source size, not TiKV-size estimate. That preserves progress without requiring the estimate task, but node sizing remains approximate as it was before reservation-specific sizing.