Skip to content

Refactor Subject (resource identifiers / urls / dids / ids) #1139

Open

Description

@joepio

I want to very severely change how AtomicServer uses URLS / IDs / Subjects. Right now, Resources are identified by HTTP strings. This has some issues:

When migrating to a different Subject type, I think we should also have these considerations in mind:

  • We have to get rid of a lot of Db:get_server_url, which we used to construct Subjects for endpoints. We should use
  • A single AtomicServer instance can have multiple subdomains (Wildcard subdomains #502), for different drives. The subject type should work with subdomains.
  • I think it should probably be some new type of struct / enum. It should probably be domain agnostic, but it should be aware of a potential subdomain if added. Could internally use Url
  • It should probably be able to handle multiple types of URL schemas, like did:ng or did:ad. I don't know exactly how these should work. When resolving these resources, the logic will be different.
  • Maybe a URL type suffices. Maybe we transform request to the current instace to some this-server domain or something.
  • Resources internally should not have the current domain hardcoded in their strings, including their references to other internal resources. These should maybe all use this-server as domain.
  • We'll need a migration script to update existing Subjects
  • Existing HTTP URLs should continue to work, of course
  • A single AtomicServer can be available on multiple URLS. For example, with multiple subdomains. Or on an IP. All of these should work. They should just emit other Subjects, depending on who requests it. So they are dynamic, need to be set when serializing the data. This has impact on Commits! I think this is where we really need the new "first commit signature" identifier that I describe in In search of the perfect identifier: about subjects, URLs, CIDs and more #1114

Related to:

Activity

  1. self-assigned this
    on Feb 5, 2026
  2. joepio commented on Feb 6, 2026

    @joepio
    MemberAuthor

    Currently working on an approach where we have a new Subject enum (either external, internal, or did). Also trying to get rid of all the server_url calls and ENV, since servers can have multiple, and we want this to be request / origin dependent.

    Biggest thing that I kind of forgot about, was that this also means that subject in Commits can move. And that's a problem, because Commits are immutable. The solution here, IMO, is to use did:ad where we don't use the domain of the server but we use the signature. I think we should include at least a hint of where the server (or servers!) is available, though. Maybe an array of hosts as a property in the Resource? Maybe also later add a pretty-url or slug that has a space within that host!

  3. joepio commented on Feb 6, 2026

    @joepio
    MemberAuthor

    I'm thinking about did:ad resources and hierarchies. Since did:ad things can be created basically anywhere, we may have to consider how they work in a hierarchy. If it's an HTTP parent, how do we deal with rights? Typically, we fetch the parent and check their rights. But what if that parent is offline? We don't want to prevent the user from making commits of course. We could allow that to happen regardless, a server can still reject commits if they don't comply. But that could lead to inconsistencies. We could also let a creator of a resource always edit it. Or maybe explicitly add a write attribute with the creator.

  4. joepio commented on Feb 6, 2026

    @joepio
    MemberAuthor

    We're getting closer to being compatible with did, but we're gonna encounter a problem.

    The W3C did spec requires the did resource to resolve to a JSON-LD file with an @context, an id and a verificationMethod. The rest is optional. Would require a custom serializer though, because JSON-LD properties are typically not valid atomic data (although the inverse IS true!)

  5. added a commit that references this issue on Mar 19, 2026
  6. joepio commented on Mar 24, 2026

    @joepio
    MemberAuthor

    I'm currently adding did:ad:{genesis} and did:ad:{agentPubKey) and did:ad:{commit} resource types.

    I'm pondering to allow did:ad:{genesis}/path. For now, it's not permitted, but perhaps it makes sense if we constrain it enough. Some thoughts:

    • We only allow it if the path resource is some child of the genesis root.
    • It can have human readable paths.
    • Retrieve the root, and get all the children too. This leads to less calls / more efficiency.
    • It introduces a new kind of decision for (API) users: should this be a resource or a sub-resource?
    • We could use it to do write permission checks. This topic, in particular, is on my mind a lot lately. How do we, a decentralized way, make sure that write permission checks are consistent? Since resources can defer write rights to parents (that's the whole idea of hierarchy), and they only have did references, systems can disagree on who can write what. Maybe one of the instances isn't aware that some other instance has removed an agent's write access. When replaying the commits of that agent, the instances can disagree on who can write - or who was able to write at what time. If we simply set write rights at the resource level, and we do more with write resources
  7. joepio commented on Mar 26, 2026

    @joepio
    MemberAuthor

    @Polleps mentioned an aspect of ULIDS that I haven't considered: the option to sort by date. It's kinda neat if we can do this. We could prepend the signature with a few bytes to include the genesis timestamp.

    • Allows sorting by creation date very easily, good for quick UIs where we only have the subjects
    • Can be gamed - users can fake timestamps.
    • Makes IDs larger - is it worth the cost?
  8. joepio commented on Apr 9, 2026

    @joepio
    MemberAuthor

    I think we should use base62 instead of base64, get rid of the + and / characters. The / especially is problematic when parsing it as URL.

  9. joepio commented on Sep 12, 2026

    @joepio
    MemberAuthor

    Backlog consolidation requested by the maintainer. Consolidated identifier-design backlog: retain legacy HTTP identity/domain migration and redirects (#590, #749), non-path client-created IDs (#593), and identifier/authorship/resolution tradeoffs (#1114). Subject/DID infrastructure now exists, but these closures do not assert that every legacy migration or resolution edge case is solved. Keep remaining concrete work in this tracker and #1210 for human-readable routing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions