Codebase Server API: `/namespace` — namespace details

[hojberg]

To support nice URLs in the Codebase UI—both local and on Share—we need to be able to ask the codebase server the hash of a namespace name as well the hash of the whole codebase when given a special argument.

Additionally we want to support readme's and metadata features for rendering them nicely in the UI.

Completing this ticket will support and unblock these UI tickets:

• https://github.com/unisonweb/codebase-ui/issues/78
• https://github.com/unisonweb/unison-local-ui/issues/3
• https://github.com/unisonweb/codebase-ui/issues/153
• https://github.com/unisonweb/codebase-ui/issues/144

Suggested API

• Namespace details: /namespace?namespace=.base
• Namespace details: /namespace?namespace=#asdiojw213dq2—querying details by hash should also be possible
• Codebase details: /namespace—without a namespace, it returns namespace details for the whole codebase
  • Alternatively this could be /namespace?namespace=.

Suggested Response Schema

-- Main response

type NamespaceResponse = {
  name: String, -- ".base",
  hash: String, -- "#asdiojw213dq2",
  readme: Maybe Doc, -- Same structure as definition docs, a tree of doc elements, could be a nullable field instead of maybe since this is JSON
  metadata: {
    numAuthors: Nat,
    numCopyrightHolders: Nat
    numLicenses: Nat
    createdAt: String, -- ISO 8601 formatted date time 
    updatedAt: String -- ISO 8601 formatted date time
  }
}

Alternatively, instead of counts of metadata (counts were used since the UI shows a list of counts in the sidebar before the user clicks through), it could be a list of hashes that could be queried separately.

https://github.com/unisonweb/unison/issues/2172 was factored out of this, but could easily be merged back into here — the major consideration was about how long it takes to compute all metadata from a whole namespace subtree.

❗This is dependent on https://github.com/unisonweb/unison/issues/2205

[hojberg]

After talking to @runarorama we realized we can get the core of this data from the /list endpoint already and we can use this for now. We'll move the metadata requesting to 2 separate endpoints: 1 for metadata about the codebase (like default author etc) and 1 for metadata about a namespace that is an aggregate of all linked objects within.

Here's the 2 tickets:

https://github.com/unisonweb/unison/issues/2186 https://github.com/unisonweb/unison/issues/2185

[hojberg]

@runarorama I'm re-opening this I think the README portion of this isn't ideal. With the /list API we'd have to have 3 dependent requests which is a lot of complexity and pain for the frontend for share:

1. GET /list of a namespace
2. If it includes a readme that is a doc then it's a project - if not then show a whole page error?
3. Fetch Readme doc to render - if exists

With the example in the description: GET /namespace would allow all of this in 1 request. We could add the readme to the /list endpoint, but it feels like /list serves a different purpose to me.