Central Registration - nosinovacao/name-sdk GitHub Wiki

Turned on by default, Central Registration is the optional mechanism in the SDK that allows an application to register itself over HTTP on a set of pre-established endpoints using well-established interfaces.

You can use our existing open-source Central Registration solution. Or you can build your own based on the functioning defined here.

How it works?

Simply put, the SDK does not have knowledge of central registration logic, it tries to submit its information to an endpoint and keep it updated, letting the service have some control over the NAME functionalities.

All the communications between the SDK and the Central Registration server are made with JSON over HTTP.

Stages

Central Registration in NAME consists of 3 key stages, and while each of them has its importance, they can be enabled/disabled using the RunningMode override.

Bootstrap

First point of contact with the server, executed only once per application lifecycle. NAME sends its information to the Registry and expects a session identifier and optional settings overrides. If this stage succeeds, the next stages will use this endpoint. This operation as a default timeout of 5 seconds, any Central Registration service should take that in mind, and keep this as a real-time operation.

Example

POST http://registry1.name.local.internal:80/api/v1/registrar

{
    "SupportedProtocols": [
        1
    ],
    "Hostname": "machine-name",
    "NAMEEndpoint": "/manifest",
    "NAMEPort": 80,
    "AppName": "Some.Service.Api",
    "AppVersion": "3.0.1",
    "NAMEVersion": "1.0.0"
}

Response: 200 OK

{
    "Protocol": 1,
    "SessionId": "453c62cc-7433-406e-86f9-24d63450fa35",
    "Overrides": {
        "ServiceDependencyMaxHops": 3,
        "ConnectedDependencyShowConnectionString": false,
        "RunningMode": 1
    }
}

Announce

Stage where the manifest is updated on the server. Executed every 10 minutes, NAME uses the identifier acquired in the Bootstrap stage to send an updated version of the Manifest. If the manifest did not change since the last Announce, a Ping will be performed instead.

Example

POST http://registry1.name.local.internal:80/api/v1/registrar/453c62cc-7433-406e-86f9-24d63450fa35/manifest

{
    "Manifest": "{\r\n \"nameVersion\": \"1.0.0\",\r\n \"name\": \"Name.Registry.Web\",\r\n \"version\": \"1.0.0\",\r\n \"infrastructure_dependencies\": [\r\n ],\r\n \"service_dependencies\": [\r\n {\r\n \"name\": \"NAME.Registry.API\",\r\n \"error\": \"Dependency Service is not reachable!\",\r\n \"min_version\": \"1.0.0\",\r\n \"max_version\": \"*\"\r\n }\r\n ]\r\n}"
}

Response: 200 OK

Ping

Stage where the application sends an heartbeat to the server. Executed every 5 minutes, NAME uses the identifier acquired in the Bootstrap stage to perform an HEAD request in the server.

Example

HEAD http://registry1.name.local.internal:80/api/v1/registrar/453c62cc-7433-406e-86f9-24d63450fa35/ping

Response: 200 OK

Central Registration Flow

The flow for the Central Registration is explained in the following flow chart.

Settings

The Central Registration settings are based on a standard/convention makes the installation of NAME more plug-and-play and less error-prone.

This does not mean these settings can not be overriden, you can override this settings using the Central Registration server Bootstrap response or, changing the dependecies.json file.

Bellow, is an explanation of all the settings that can be overriden and how they will impact the Central Registration behaviour.

Registry Endpoints

The endpoints to which the SDK will try to connect to are, by default:

• http://registry1.name.local.internal:80/api/v1
• http://registry2.name.local.internal:80/api/v1
• http://registry1-name:80/api/v1
• http://registry2-name:80/api/v1

The SDK will try to bootstrap in order to these endpoints, one by one, until one of them responds with a valid message.

Running Modes

Running modes define how NAME will interact with the Central Registration throughout its lifecycle. The following table specifies how each of the setting will change the NAME behaviour. By default this is set to Standard.

Setting	Value	Announces	Pings	Bootstraps	Exposes Manifest
Standard	0	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:
AnnounceDisabled	1	:red_circle:	:white_check_mark:	:white_check_mark:	:white_check_mark:
HeartbeatDisabled	2	:red_circle:	:red_circle:	:white_check_mark:	:white_check_mark:
BootstrapDisabled	3	:red_circle:	:red_circle:	:red_circle:	:white_check_mark:
NAMEDisabled	4	:red_circle:	:red_circle:	:red_circle:	:red_circle:

Registry Ping Frequency

Defines the frequency at which NAME will perform the Ping stage, might be useful to set depending on the criticity of a service. By default it is set to 5 minutes.

Registry Re-Announce Frequency

The frequency at which NAME will perform the Announce stage, this value should be set very high, as it may provide the most useful part of sending the manifest to the Central Registration service, when there is some problem with your dependencies. By default it is 10 minutes.

Registry Bootstrap Retry Frequency

When NAME can not talk to the Central Registration service it will keep trying to register with all the endpoints, this value sets the frequency at which it will happen. By defaulti it is 1 hour.

Registry Bootstrap Timeout

This setting defines the timeout value for the Bootstrap stage, this should be kept at a low value in order to not lose many time, waiting for non existent servers to respond.