Context
After the Azure Blob / Tencent COS / OneDrive connector work, several names that still contain s3 now describe broader object-storage behavior. Some of these names are valid and should remain because they are public wire values, historical migration facts, or truly S3-compatible concepts. Others are internal/UI names that now mislead contributors and users.
This issue tracks the naming debt so we can clean it up in safe batches instead of doing a risky global rename.
Keep as-is or change only with a compatibility plan
These names are public contract, migration history, or true S3-compatible driver concepts:
driver_type = "s3" / DriverType::S3
- Public wire value and DB enum. Keep.
s3_upload_strategy / s3_download_strategy
- Existing
StoragePolicyOptions JSON fields. Azure Blob / Tencent COS currently reuse them. Do not rename directly without serde aliasing, DB backfill, OpenAPI/frontend compatibility, and docs.
s3_path_style
- Actual S3-compatible path-style concept. Keep.
S3TempKey / S3MultipartId in old migrations
- Migration history. Do not rewrite.
S3Driver, S3Connector, aws_sdk_s3, s3_config, normalize_s3_endpoint_and_bucket
- Real S3-compatible driver code. Keep.
RemoteCreateS3IngressProfileRequest
- Managed follower ingress currently supports local and s3 targets. Keep unless that model expands.
Names that now have broader object-storage meaning
These should be cleaned up gradually with aliases or internal renames:
S3UploadStrategy / S3DownloadStrategy
- Defined in
src/types/storage_policy.rs.
- Now used by S3-compatible, Azure Blob, and Tencent COS connector paths.
- Candidate alias/new name:
ObjectStorageUploadStrategy / ObjectStorageDownloadStrategy.
StorageConnectorCapabilities.s3_transfer_strategy
- Defined in
src/storage/connector_descriptor.rs.
- Actual meaning is “connector exposes object-storage upload/download strategy options”.
- Candidate new field:
object_storage_transfer_strategy, keeping s3_transfer_strategy for compatibility for at least one release.
StorageConnectorUploadTransport::ObjectStorage(S3UploadStrategy)
- Defined in
src/storage/connectors/upload.rs.
- Outer enum is already object-storage scoped; inner enum name is too narrow.
effective_s3_upload_strategy() / effective_s3_download_strategy()
- Defined in
src/types/storage_policy.rs.
- Add
effective_object_storage_upload_strategy() / effective_object_storage_download_strategy() and migrate call sites.
s3_part_number
- Used in
src/services/upload_service/chunk.rs.
- Multipart part numbering is now object-storage / remote multipart behavior.
- Candidate name:
object_part_number.
S3_PROCESSING_PROGRESS
- Used in
frontend-panel/src/components/files/uploadResume.ts.
- It is just upload finalization/progress scaling, not S3-specific.
- Candidate name:
SERVER_FINALIZE_PROGRESS or REMOTE_PROCESSING_PROGRESS.
- Frontend component/function names:
S3UploadStrategyField
S3DownloadStrategyField
S3ConnectionFields where used for generic object-storage descriptors
supportsS3TransferStrategy
normalizeS3ConnectionFields where used outside true S3-compatible profile handling
- Frontend i18n display strings:
s3_upload_strategy: currently “S3 Upload Strategy” / “S3 上传方式”
s3_download_strategy: currently “S3 Download Strategy” / “S3 下载方式”
- These labels are confusing when the selected connector is Azure Blob or Tencent COS. The key can stay initially, but displayed copy should say “Object Storage Upload Strategy” / “对象存储上传方式”.
Suggested migration plan
Batch 1: low-risk internal/UI cleanup
- Rename
S3_PROCESSING_PROGRESS to a provider-neutral name.
- Change UI labels for
s3_upload_strategy / s3_download_strategy to object-storage wording without changing the JSON keys.
- Add
supportsObjectStorageTransferStrategy() as the preferred predicate and keep supportsS3TransferStrategy() as a temporary alias.
- Add provider-neutral component names for upload/download strategy fields, keeping the wire field names unchanged.
- Rename local variables like
s3_part_number to object_part_number where no public API is affected.
Batch 2: Rust aliases/helpers
- Add type aliases or new internal names:
ObjectStorageUploadStrategy
ObjectStorageDownloadStrategy
- Add helper methods:
effective_object_storage_upload_strategy()
effective_object_storage_download_strategy()
- Move connector/upload-service call sites to the object-storage helper names while keeping serialized fields unchanged.
Batch 3: descriptor/API compatibility work, if we still want it
- Add
object_storage_transfer_strategy to connector descriptor output.
- Keep
s3_transfer_strategy for generated clients and existing frontend code during a compatibility window.
- Update OpenAPI, generated frontend types, and descriptor tests.
Do not do casually
- Do not directly rename
s3_upload_strategy / s3_download_strategy in persisted policy JSON without a proper migration and serde compatibility story.
- Do not rename
driver_type = "s3"; this is still the correct S3-compatible driver type.
- Do not rewrite old migration enum names just to make them pretty.
Search notes
The main places found during the audit:
src/types/storage_policy.rs
src/storage/connector_descriptor.rs
src/storage/connectors/upload.rs
src/storage/connectors/{s3,azure_blob,tencent_cos}.rs
src/services/upload_service/chunk.rs
frontend-panel/src/components/files/uploadResume.ts
frontend-panel/src/components/admin/storage-policy-dialog/*S3*
frontend-panel/src/components/admin/storage-policy-dialog/descriptorPredicates.ts
frontend-panel/src/i18n/locales/{zh,en}/admin/policies.json
developer-docs/** and docs/** where user-facing wording should distinguish S3-compatible from general object storage
Acceptance criteria
- New internal code uses object-storage naming for behavior shared by S3-compatible, Azure Blob, and Tencent COS.
- Public wire fields remain backward compatible.
- Admin UI does not label Azure Blob / Tencent COS transfer settings as “S3 upload/download strategy”.
- Tests cover compatibility for existing
s3_upload_strategy / s3_download_strategy policy JSON.
Context
After the Azure Blob / Tencent COS / OneDrive connector work, several names that still contain
s3now describe broader object-storage behavior. Some of these names are valid and should remain because they are public wire values, historical migration facts, or truly S3-compatible concepts. Others are internal/UI names that now mislead contributors and users.This issue tracks the naming debt so we can clean it up in safe batches instead of doing a risky global rename.
Keep as-is or change only with a compatibility plan
These names are public contract, migration history, or true S3-compatible driver concepts:
driver_type = "s3"/DriverType::S3s3_upload_strategy/s3_download_strategyStoragePolicyOptionsJSON fields. Azure Blob / Tencent COS currently reuse them. Do not rename directly without serde aliasing, DB backfill, OpenAPI/frontend compatibility, and docs.s3_path_styleS3TempKey/S3MultipartIdin old migrationsS3Driver,S3Connector,aws_sdk_s3,s3_config,normalize_s3_endpoint_and_bucketRemoteCreateS3IngressProfileRequestNames that now have broader object-storage meaning
These should be cleaned up gradually with aliases or internal renames:
S3UploadStrategy/S3DownloadStrategysrc/types/storage_policy.rs.ObjectStorageUploadStrategy/ObjectStorageDownloadStrategy.StorageConnectorCapabilities.s3_transfer_strategysrc/storage/connector_descriptor.rs.object_storage_transfer_strategy, keepings3_transfer_strategyfor compatibility for at least one release.StorageConnectorUploadTransport::ObjectStorage(S3UploadStrategy)src/storage/connectors/upload.rs.effective_s3_upload_strategy()/effective_s3_download_strategy()src/types/storage_policy.rs.effective_object_storage_upload_strategy()/effective_object_storage_download_strategy()and migrate call sites.s3_part_numbersrc/services/upload_service/chunk.rs.object_part_number.S3_PROCESSING_PROGRESSfrontend-panel/src/components/files/uploadResume.ts.SERVER_FINALIZE_PROGRESSorREMOTE_PROCESSING_PROGRESS.S3UploadStrategyFieldS3DownloadStrategyFieldS3ConnectionFieldswhere used for generic object-storage descriptorssupportsS3TransferStrategynormalizeS3ConnectionFieldswhere used outside true S3-compatible profile handlings3_upload_strategy: currently “S3 Upload Strategy” / “S3 上传方式”s3_download_strategy: currently “S3 Download Strategy” / “S3 下载方式”Suggested migration plan
Batch 1: low-risk internal/UI cleanup
S3_PROCESSING_PROGRESSto a provider-neutral name.s3_upload_strategy/s3_download_strategyto object-storage wording without changing the JSON keys.supportsObjectStorageTransferStrategy()as the preferred predicate and keepsupportsS3TransferStrategy()as a temporary alias.s3_part_numbertoobject_part_numberwhere no public API is affected.Batch 2: Rust aliases/helpers
ObjectStorageUploadStrategyObjectStorageDownloadStrategyeffective_object_storage_upload_strategy()effective_object_storage_download_strategy()Batch 3: descriptor/API compatibility work, if we still want it
object_storage_transfer_strategyto connector descriptor output.s3_transfer_strategyfor generated clients and existing frontend code during a compatibility window.Do not do casually
s3_upload_strategy/s3_download_strategyin persisted policy JSON without a proper migration and serde compatibility story.driver_type = "s3"; this is still the correct S3-compatible driver type.Search notes
The main places found during the audit:
src/types/storage_policy.rssrc/storage/connector_descriptor.rssrc/storage/connectors/upload.rssrc/storage/connectors/{s3,azure_blob,tencent_cos}.rssrc/services/upload_service/chunk.rsfrontend-panel/src/components/files/uploadResume.tsfrontend-panel/src/components/admin/storage-policy-dialog/*S3*frontend-panel/src/components/admin/storage-policy-dialog/descriptorPredicates.tsfrontend-panel/src/i18n/locales/{zh,en}/admin/policies.jsondeveloper-docs/**anddocs/**where user-facing wording should distinguish S3-compatible from general object storageAcceptance criteria
s3_upload_strategy/s3_download_strategypolicy JSON.