Related Issue

Closes #6647

Rationale

This PR centralizes all date/time-related logic within OpenDAL. By introducing a new Timestamp wrapper in core/src/raw/time.rs, direct usage of jiff::Timestamp throughout the codebase is removed.

Key benefits:

• Simplified API: Provides convenience methods like now(), from_millisecond(), and format_http_date().
• Consistent error handling: Converts jiff errors into OpenDAL's Error type.
• Type safety: Prevents external jiff types from leaking into the public API.
• Future-proof design: Makes it easier to adapt to potential date/time library changes.

Changes included in this PR

Core Implementation (8 commits)

1. Add Timestamp wrapper (time.rs)

• Introduced a new Timestamp wrapper around jiff::Timestamp in core/src/raw/time.rs.
• Implemented conversion traits: From, TryFrom, FromStr.
• Added formatting methods: format_http_date, format_rfc3339, format_iso8601.
• Added helper constructors: now, from_millisecond, from_second.

2. Remove jiff_util module

• Deleted the obsolete core/src/raw/jiff_util.rs.
• Updated core/src/raw/mod.rs to expose the new Timestamp type.

3. Update raw layer utilities

• Refactored adapters, http_util, and ops to use the Timestamp wrapper.

4. Update types layer

• Updated metadata, options, and operator to use the Timestamp wrapper.

5. Migrate cloud storage services

• Services: S3, GCS, Azure Blob/DLS/File, Tencent COS, Alibaba OSS, Backblaze B2, Aliyun Drive, Vercel Blob, Cloudflare KV.
• Metadata parsing and formatting now use the Timestamp wrapper.

6. Migrate filesystem services

• Services: Local FS, HDFS, HDFS Native, SFTP, WebHDFS, WebDAV, FTP, MonoioFS, Alluxio, CompFS.
• Updated file metadata, system time conversions, and listers/writers to use Timestamp.

7. Migrate other services

• Services: Dropbox, OneDrive, Google Drive, pCloud, GitHub, Hugging Face, Koofr, LakeFS, Seafile, Yandex Disk, UpYun, Swift, cacache, dashmap, mini_moka, DBFS.
• Integrated the Timestamp wrapper.

8. Update Cargo.lock

• Refreshed dependency lockfile to reflect the Timestamp migration.

Bindings & Integrations Fixes (5 commits)

9. Fix bindings and add as_millisecond() method

Files:

• core/src/raw/time.rs - Added missing as_millisecond() method
• bindings/c/src/metadata.rs - Use as_millisecond() instead of manual calculation
• integrations/object_store/src/lib.rs - Use into_inner() for proper conversion
• bindings/python/src/options.rs - Revert to Option<Timestamp> (was temporarily Option<String>)
• bindings/python/src/metadata.rs - Revert to Option<Timestamp>

Rationale: During initial implementation, temporary workarounds (manual calculations, string conversions) were used to unblock testing. This commit properly adds the missing as_millisecond() method and removes all temporary code.

10. Add Python datetime integration

Files: bindings/python/src/lib.rs, bindings/python/src/metadata.rs, bindings/python/src/options.rsImplementation:

• Created Python-specific Timestamp wrapper type in bindings layer
• Implemented IntoPyObject<'py> trait to convert Timestamp → Python datetime
• Implemented FromPyObject<'py> trait to convert Python datetime → Timestamp
• Leverages PyO3's jiff-02 feature for automatic jiff::Timestamp ↔ Python datetime conversion
• Core library remains free from PyO3 dependencies

11. Fix fuse3 integration

File: integrations/fuse3/src/file_system.rs

• Updated metadata2file_attr() to use .into_inner() for Timestamp → SystemTime conversion

12. Format object_store integration

File: integrations/object_store/src/lib.rs

• Applied cargo fmt to format multi-line function calls

13. Fix unftp-sbe integration

File: integrations/unftp-sbe/src/lib.rs

• Updated OpendalMetadata::modified() to use .into_inner() for Timestamp → SystemTime conversion

Helper function replacements

Throughout the migration:

• Replaced parse_datetime_from_rfc3339() → str.parse::<Timestamp>().
• Replaced parse_datetime_from_timestamp_millis() → Timestamp::from_millisecond().
• Replaced direct jiff::Timestamp usage → Timestamp wrapper.

Commit Summary

Architecture Decisions

Why a wrapper instead of type alias?

• Encapsulation: Hides jiff::Timestamp implementation details
• Method additions: Can add OpenDAL-specific convenience methods
• Future flexibility: Easy to swap underlying library if needed
• API clarity: Makes timestamp handling explicit in function signatures

Language bindings strategy

Each language binding handles Timestamp conversion in its own layer:

• Python: Custom wrapper type with PyO3 traits (IntoPyObject, FromPyObject)
• C: Direct as_millisecond() for simple integer representation
• Java/Node.js: Use existing datetime conversion patterns

This approach keeps the core library clean and allows each binding to use its language's native datetime types.

Local Verification

• ✅ cargo fmt --check
• ✅ cargo check -p opendal --features="blocking"
• ✅ cargo clippy -p opendal --features="blocking" -- -D warnings
• ✅ cargo test -p opendal --features="blocking,services-s3,services-fs" (All 319 tests passed)
• ✅ cargo check (Python bindings) - Compilation successful
• ✅ cargo clippy (Python bindings) - No warnings

Breaking Changes

⚠️ Public API Changes

Type Changes:

• Metadata::last_modified() return type changed
  from Option<jiff::Timestamp> to
  Option<Timestamp> (our new wrapper type)
• Read/write/stat options now use Timestamp
  wrapper instead of direct jiff::Timestamp

Impact:
If your code directly references jiff::Timestamp
types from OpenDAL's public API, you'll need to
update it to use the Timestamp wrapper after
this PR is merged.

Rationale:
This change prevents internal implementation
details (like jiff::Timestamp) from leaking into
OpenDAL's public API, improving type safety and
future extensibility.

Migration Example

// Before
let ts: Option<jiff::Timestamp> =
metadata.last_modified();

// After
let ts: Option<Timestamp> =
metadata.last_modified();
// Use wrapper methods like .as_millisecond(),
.format_http_date(), etc.

Review Request

1
Please share your feedback on this public API change.
If there are project policies or better approaches to consider, I'm happy to adjust accordingly.

2
I’ve looked into the current CI failures.

From the logs, it appears that the issue isn’t with the Rust code I modified. Instead, the failures occur during the Java binding build process when attempting to access the Maven Central repository. The build is consistently encountering 503 Service Temporarily Unavailable errors (and occasionally 500 Internal Server Error).

Specifically, the build fails when trying to download certain artifacts (such as plexus-classworlds or google-java-format) due to error responses from external Maven servers. This seems to be a temporary network issue or instability on the Maven Central server itself.

I’ve retried the CI a few times, but the same errors persist.
My Rust code compiles cleanly and passes all checks, so this Maven error does not appear to be related to my changes.
Could you advise if there’s anything I can do in this situation, or should we wait for the Maven servers to stabilize? Thank you.