Account Lifecycle Best Practices

[bnewbold]

This is a section of the Account Hosting specification which we have pulled out to a less formal document for now.

This document summarizes the expected behaviors for a few common account lifecycle transitions, and what firehose events are expected in what order. Software is generally expected to be resilient to partial or incorrect event transmission.

New Account Creation: when an account is registered on a PDS and a new identity (DID) is created.

• the PDS will generate or confirm the existence of the account's identity (DID and handle). Once the DID is in a confirmed state that can be resolved by other services in the network, and points to the current PDS instance, the PDS emits an #identity event. It is good, but not required, to wait until the handle is resolvable by third parties before emitting the event (especially, but not only, if the PDS is providing a handle for the account). The account status may or may not be active when this event is emitted.
• once the account creation has completed, and the PDS will respond with active to API requests for account status, an #account event can be emitted
• when the account's repository is initialized with a rev and commit, a #commit message can be emitted. The initial repo may be "empty" (no records), or may contain records.
• the specific order of events is not formally specified, but the recommended order is: #identity, #account, #commit
• downstream services process and pass through these events

Account Migration: is described in more detail below, but the relevant events and behaviors are:

• the new PDS will not emit any events on initial account creation. The account state will be deactivated on the new PDS (which will reply as such to API requests)
• when the identity is updated and confirmed by the new PDS, it should emit an #identity event
• when the account is switched to active on the new PDS, it should emit an #account event and a #commit event; the order is not formally required, but doing #account first is recommended. Ideally the #commit event will be empty (no new records), but signed with any new signing key, and have a new/incremented rev.
• when the account is deactivated on the old PDS, it should emit an #account event, indicating that the account is inactive and has status deactivated.
• Relays should ignore #account and #commit events which are not coming from the currently declared PDS instance for the identity: these should not be passed through to the output firehose. Further, they should ignore #commit events when the local account status is not active. Overall, this means that account migration should result in three events coming from the relay: an #identity (from new PDS), an #account (from new PDS), and a #commit (from new PDS). The #account from the old PDS is usually ignored.
• downstream services (eg, AppView) should update their identity cache, and increment the account's rev (when the #commit is received), but otherwise don't need to take any action.

Account Deletion:

• PDS emits an #account event, with active false and status deleted.
• Relay updates local account status for the repo, and passes through the #account event. If the Relay is a full mirror, it immediately stop serving getRepo, getRecord, and similar API requests for the account, indicating the reason in the response error. The Relay may fully delete repo content locally according to local policy. The firehose backfill window does not need to be immediately purged of commit events for the repo, as long as the backfill window is time-limited.
• the PDS should not emit #commit events for an account which is not "active'. If any further #commit messages are emitted for the repo (eg, by accident or out-of-order processing or delivery), all downstream services should ignore the event and not pass it through
• downstream services (eg, AppView) should immediately stop serving/distributing content for the account. They may defer permanent data deletion according to local policy. Updating aggregations (eg, record counts) may also be deferred or processed in a background queue according to policy and implementation. Error status messages may indicate either that the content is "gone" (existed, but no longer available), or that content is "not found" (not revealing that content existed previously)

Account takedowns work similarly to account deletion.

Account Deactivation:

• PDS emits an #account event, with active false and status deactivated.
• similar to deletion, Relay processes the event, stops redistributing content, and passes through the event. The Relay should not fully purge content locally, though it may eventually delete local copies if the deactivation status persists for a long time (according to local policy).
• similar to deletion, #commit events should not be emitted by the PDS, and should be ignored and not passed through if received by Relays
• downstream services (eg, AppViews) should make content unavailable, but do not need to delete data locally. They should indicate account/content status as "unavailable"; best practice is to specifically indicate that this is due to account deactivation.

Account suspension works similarly to deactivation.

Account Reactivation:

• PDS emits an #account event, with active status.
• Relay verifies that the account reactivation is valid, eg that it came from the current PDS instance for the identity. It updates local account status, and passes through the event.
• any downstream services (eg, AppViews) should update local account status for the account.
• any service which does not have any current repo content for the account (eg, because it was previously deleted) may fetch a repo CAR export and process it as a background tasks. An “upstream” host (like a relay) may have a repo copy, or the service might connect directly to the account’s PDS host. They are not required to do so, and might instead wait for a #commit event.
• if the account was previously deleted or inactive for a long time, it is a best practice for the PDS to emit an empty #commit event after reactivation to ensure downstream services are synchronized

[costinm]

Perhaps for account migration the old PDS should emit a different event type or status - do differentiate from ''deactivated ? Or no event at all - nothing should rely on this, the old PDS may be gone or not cooperating. Or at least clarify that old PDS will have active=true.

[bnewbold]

Part of the motivation of updating state at the old PDS is to ensure that PDS knows that the account migration even happened in the first place. PDS instances don't consume from the firehose so they might not know. We also recommend it emit an event as a belt-and-suspenders thing, for example for Relay instances which are not (yet) connected to the new PDS instance.

I'm not sure a distinct status type is needed: an account which has migrated has the same semantics as a deactivated or deleted account. One use-case would be to provide more helpful error messages; we have a tracking issue for that here:
#3174