Make Timestamp a special SATS type

[gefjon]

Description of Changes

• Add timestamp as a new "special" AlgebraicType.
• Move Timestamp to the SATS crate, where previously it was in both bindings and client-api-messages.
  • Other special types are mostly defined in lib, which seems wrong to me.
• Update Rust client SDK and codegen to use Timestamp rather than u64.
• Make Timestamp store micros_since_unix_epoch: i64, where previously it had micros_since_unix_epoch: u64.
  • Signed value lets us represent dates before the Unix epoch, which Rust SystemTime and C# DateTime(Offset) can do.
  • Retaining 64-bit microseconds keeps us binary-compatible with past versions.
• Add TimeDuration, analogous to Duration and TimeSpan, as another new "special" AlgebraicType.
• TimeDuration is micros: i64, to match Timestamp.
  • I'm not sure this is the right choice; C# has signed TimeSpan but Rust has unsigned Duration.
  • Different operations become fallible or infallible depending on which you choose.
  • Honestly I doubt it really matters.
• ScheduleAt stores Timestamp or TimeDuration in its two variants.
  • Use in ScheduleAt::Interval means arguably we want unsigned TimeDuration, as a negative interval seems meaningless.
  • Currently using the magnitude / absolute value, so that ScheduleAt::Interval(-10 minutes) is the same as ScheduleAt::Interval(10 minutes).
  • Again, probably doesn't really matter, as most users will construct ScheduleAts via Duration::into, I hope.
• Update the WebSocket protocol to use these new SATS types rather than raw u64s.

Companion PRs:

• TypeScript SDK.
• Private.
• C# client SDK.

Still TODO:

• Update docs.

API and ABI breaking changes

• Timestamp type (e.g. in ReducerContext) is now defined in the SATS crate, re-exported from lib and bindings, and has slightly different methods.
  • Most notably, Timestamp::now is deprecated and stubbed in the WASM target.
• The SATS type and serialization of Timestamp is changed from U64 to Product { __timestamp_micros_since_unix_epoch__: I64 }. This is layout-equivalent in BSATN and I think BFLATN, but changes the JSON format. It will also make old ModuleDefs / system tables detect a migration.
• WebSocket message schema changed to use new types.

Expected complexity level and risk

2 - Changing the SATS definitions of types has been shown recently to be potentially scary. On the other hand, this redefinition is layout-compatible, so should be much less breaking than when we redefined Identity.

Testing

Describe any testing you've done, and any testing you'd like your reviewers to do,
so that you're confident that all the changes work as expected!

• Added unit tests that Timestamp is well-behaved and compatible with SystemTime.
• Added SDK tests for the same.
• Whatever needs to happen to test with C# and TypeScript.

[gefjon]

Having discussed this more with the team, there's an additional wrinkle: while C#'s DateTime is semantically correct as a translation for AlgebraicType::timestamp(), use of that type is fraught because of its locale-dependent printing. I have been encouraged to prefer DateTimeOffset, which maintains locale-independent printing by encoding a time zone, but that's no good because we don't store the time zone in AlgebraicType::timestamp() and so would have to discard it when serializing. We would still be representing the same point in time, but it would be, say, 12:00 UTC rather than 7:00 EST. Implicitly losing information in this way seems undesirable.

My disposition is to avoid these tough questions by retaining spacetimedb::Timestamp as a user-facing type (adding it to the client SDKs) and providing methods on it to convert to and from SystemTime or DateTimeOffset.

I'm also interested in providing a special SATS type analogous to Rust Duration or C# TimeSpan, for storage in ScheduleAt::Interval. I'm not sure what to name this type - I would prefer not to use either Duration or TimeSpan to avoid confusion when writing Rust and C# respectively. I'm considering TimeDuration, which is redundant but clear and unambiguous.

[gefjon]

TODO: Switch back to micros: u64, rather than nanos: i64. The latter is likely more correct, but the former is BSATN- and BFLATN-compatible with our old code, which is more valuable than the incremental improvement in precision or the ability to represent negative durations or pre-Unix timestamps.

EDIT: micros: i64, but otherwise done.

[Centril]

Approving as code owner of websocket.rs

[kazimuth]

Approving RE: Timestamp, core, and schema.

[kazimuth]

TODO: test elapsed does not panic on 0ns duration

[gefjon]

TODO: test elapsed does not panic on 0ns duration

Turns out we don't even define elapsed, so this is a non-issue. We can add it in a follow-up.

[bfops]

My codeowned files look good given the time-sensitivity.
crates/cli/src/tasks/csharp.rs