pageserver: improve readability of shard.rs

[jcsp]

No functional changes, this is a comments/naming PR.

While merging sharding changes, some cleanup of the shard.rs types was deferred.

In this PR:

• Rename is_zero to is_shard_zero to make clear that this method doesn't literally mean that the entire object is zeros, just that it refers to the 0th shard in a tenant.
• Pull definitions of types to the top of shard.rs and add a big comment giving an overview of which type is for what.

Closes: #6072

Checklist before requesting a review

• I have performed a self-review of my code.
• If it is a core feature, I have added thorough tests.
• Do we need to implement analytics? if so did you add the relevant metrics to the dashboard?
• If this PR requires public announcement, mark it with /release-notes label and add several sentences in this section.

Checklist before merging

• Do not forget to reformat commit message to not include the above checklist

[github-actions]

No tests were run or test report is not available

Code coverage* (full report)

• functions: 28.0% (6428 of 22962 functions)
• lines: 46.6% (45012 of 96565 lines)

* collected from Rust tests only

---

_{The comment gets automatically updated with the latest test results
124c054 at 2024-04-12T12:39:28.459Z :recycle:}

[arpad-m]

On a related note, I wonder why TenantShardId is in pageserver_api: TenantId is in the utils crate instead, same for TimelineId. In #7322 I had to add a dependency on pageserver_api because of TenantShardId (it was already a transitive dependency, but still).

[jcsp]

On a related note, I wonder why TenantShardId is in pageserver_api: TenantId is in the utils crate instead, same for TimelineId.

I wanted to avoid exposing all the shard.rs content to modules that don't really talk to pageservers, as it's kind of a concept that's "owned" by the pageserver (at least, until the safekeeper becomes shard aware). In future it might be nice to define a crate for "foundational types" (or some better name) -- these ID types aren't really "utilities as such".