ADR-110: Realm description

More details about this document
Latest published version:
https://adr.decentraland.org/adr/ADR-110
Authors:
agusaldasoro
hugoarregui
menduz
Feedback:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on githistory.xyz

Abstract

This document defines the protocol to describe a realm.

Realm

A realm is a set of services needed for the client to work: current there is comms, content and lambdas. A valid realm is pointed by a URL defining /about endpoint in the proper format, which describes the realm and its status.

Usage

Realms are used by the Explorer ADR-102 to set up and configure each browsing session.

Canonically, a realm can be selected by executing the /changerealm <baseUrl> command in the chat.

Examples:

Other mechanisms may be available to resolve realm baseUrl out of a string, like the ENS resolution defined at ADR-144

/about

This endpoint must return the well-known schema defined in the protocol repository:

type About = {
  healthy: boolean
  acceptingUsers: boolean
  configurations: {
    networkId: number
    realmName?: string
    scenesUrn: string[]
    globalScenesUrn: string[]
    cityLoaderContentServer?: string
  }
  content: {
    healthy: boolean
    version?: string
    commitHash?: string
    publicUrl: string
  }
  comms: {
    healthy: boolean
    protocol: string
    fixedAdapter?: string
    usersCount?: number
  }
  lambdas: {
    healthy: boolean
    version?: string
    commitHash?: string
    publicUrl: string
  }
  bff?: {
    healthy: boolean
    userCount: number
    commitHash?: string
    publicUrl: string
  }
}

Example https://peer.decentraland.org/about:

{
  "healthy": true,
  "content": {
    "healthy": true,
    "version": "6.0.6",
    "commitHash": "d2eeccaffe2a9c22ac963348851c7791b63fc517",
    "publicUrl": "https://peer-ec2.decentraland.org/content/"
  },
  "lambdas": {
    "healthy": true,
    "version": "6.0.6",
    "commitHash": "d2eeccaffe2a9c22ac963348851c7791b63fc517",
    "publicUrl": "https://peer-ec2.decentraland.org/lambdas/"
  },
  "configurations": {
    "networkId": 1,
    "globalScenesUrn": [],
    "scenesUrn": [],
    "realmName": "hela"
  },
  "comms": {
    "healthy": true,
    "protocol": "v3",
    "commitHash": "b3ec3327ceef53473853068dcdad8ea08d7a0f9c"
  },
  "bff": {
    "healthy": true,
    "commitHash": "1a2ff915a216191ecc6ef85f3822f0809fe16f3c",
    "userCount": 4,
    "protocolVersion": "1.0_0",
    "publicUrl": "/bff"
  },
  "acceptingUsers": true
}

Example https://worlds-content-server.decentraland.org/world/menduz.dcl.eth/about:

{
  "healthy": true,
  "configurations": {
    "networkId": 1,
    "globalScenesUrn": [],
    "scenesUrn": [
      "urn:decentraland:entity:bafkreihiv5zkzjui46gvxtsnk5pfogmq7kyzijxpf3gjqlb2ivydcuwgxq?baseUrl=https://worlds-content-server.decentraland.org/contents/"
    ],
    "minimap": {
      "enabled": false
    },
    "skybox": {},
    "realmName": "menduz.dcl.eth"
  },
  "content": {
    "healthy": true,
    "publicUrl": "https://peer.decentraland.org/content"
  },
  "lambdas": {
    "healthy": true,
    "publicUrl": "https://peer.decentraland.org/lambdas"
  },
  "comms": {
    "healthy": true,
    "protocol": "v3",
    "fixedAdapter": "signed-login:https://worlds-content-server.decentraland.org/get-comms-adapter/world-prd-menduz.dcl.eth"
  },
  "acceptingUsers": true
}

Health property

healthy: boolean is used to inform whether the realm is in a healthy state, the endpoint must return an HTTP status of 200, otherwise it should return 503. This way just by checking the response HTTP status, a client looking for a realm to connect may decide whether to join or not the realm.

The healthy field in the root of the structure) will be true only if all the referenced services are healthy.

Accepting users property

acceptingUsers: boolean is used to inform whether is accepting new users. It differs from healthy in conditions like "maximum communications capacity" or "high server load".

Configurations section

Describes explorer-specific configurations.

Comms section

Describes the communications services parameters and connection information.

When protocol: "v3" is currently the only valid and implemented version of comms.

protocol: v2 was deprecated. Expand this view to see an example - If `protocol` is `v2` it will present an structure like:
{
  "comms": {
    "healthy": true,
    "protocol": "v2",
    "version": "1.0.0",
    "commitHash": "43d2173cf5e2078b32bddab5adb90e4778170c44",
    "usersCount": 152
  }
}

License

Copyright and related rights waived via CC0-1.0. DRAFT Living