Federated Learning with Nats

SymetryML can use NATS (www.nats.io) as a backend queueing system to power a federation. The REST calls to create / join a federation

Create Nats Backed Federation

URL

POST /symetry/rest/{cid}/fedml/create?pid={new-project-id} [body=Encrypted Map]

This REST endpoint allows the user to create a new federation. The user who creates the federation also becomes its administrator. The body is a map that is encoded to a JSON string and then encrypted using the user secret key.

Federation Key Map Value

Key	Required / Optional	Value Description
fed_name	Required	The name of the federation.
fed_local_type	Optional	The type of project to use. Supported values: cpu and gpu. The default value is cpu.
sync_sched	Required	The sync schedule, consult FedML Terminology for more details.
nats_hosts	Required	Urls of hosts
fed_encrypt	Optional	Whether to encrypt or not the sync message. The default is false.
nats_sec_user	Optional	When using nats user/password authentication, this allows to specify the user. https://docs.nats.io/developing-with-nats/security for more details.
nats_sec_passwd	Optional	When using nats user/password authentication, this allows to specify the user password. https://docs.nats.io/developing-with-nats/security for more details.
nats_sec_token	Optional	When using nats token authentication, this allows to specify the token to use for authentication. https://docs.nats.io/developing-with-nats/security for more details.
nats_sec_nkey_seed	Optional	When using nats NKEY authentication, this allows to specify the seed of the NKEY used. This is set by the federation administrator and will be shared with other peers when they join the federation.
nats_req_timeout	Optional	NATS request timeout in seconds, default is 30.
nats_stream_max_memory	Optional	NATS maximum memory used by underlying stream managing project sharing with other peers. The default is (1Gig, 1024 x 1024 x 1024 bytes).

Query Parameters

Parameter	Required / Optional	Description
pid	Required	Name of the new SymetryML project.
persist	Optional	Whether to persist or not the project

HTTP Responses

HTTP Status Code	HTTP Status Message	Description
201	CREATED	Success. {"statusCode":"CREATED","statusString":" + SYMETRYML Created with id:r1","values":{}}
409	CONFLICT	SymetryML project already exists. {"statusCode":"CONFLICT","statusString":" + Customer [c1] already have SYMETRYML with id[r1], ","values":{}}

HTTP Response Entity

None

Sample Request/Response Fed Create

POST url="http://charm:8080/symetry/rest/c1/fedml/create?pid=nh_test_admin

Request Body:

KjxfT4/2TpJsfwd+gAG0zAnH7r+fs7IyKrlMXNoqh5CNQjoLioBW6HjXH5hRVqEYASueMI++fmMDAEOBIQD/e/3HDeA/SVojcmzywmxcMNotH9iTpboU9KIJZVq1JW3bxAv+e2COEuI+82qrQVJ4QifuAy5TxR+B5H0GjC0x4qiDK5h+TpEDnFB1Cjdv3xQyiDW8EetZNlCcriEdkTSvxI8duhdJIhFy4UYL1XzN7SavwmE/rddP+ETfeMmLJehseBOJr19xPiMR71maM2DybESQvCN1bWUj2XEvujasrcMMUK4+NEeC0pDe+gWoJhRgAZlRnOWgdwCKeBqcmqOc9Q==

Response:

{"statusCode":"CREATED","statusString":"Project Created with id:nh_test_admin","values":{}}

Federated Learning Get Encrypted Federation Info

URL

POST /symetry/rest/{cid}/fedml/{pid}/getEncrypted

Get Encrypted Body Key Map Value.

TDB new ResponseEntityKey.

Mandatory key	Required / Optional	Value Description
passwd	Required	Password to use to encrypt the federation information
fed_rest_host	Required	Hostname where admin can be reach at.

HTTP Responses

HTTP Status Code	HTTP Status Message	Description
200	OK	Success.
400	BAD REQUEST	SymetryML project does not exist. {"statusCode":"BAD_REQUEST","statusString":"Cannot Find SYMETRYML id[r5] for Customer id [c1]","values":{}

HTTP Response Entity

The response will be stored in the fedInfoEncrypted entity which is a string. That string is in turn a json encoded string encrypted with the provided password. Once decrypted you get a <string, string> map that contains the following key: (Consult Federation Key Map for details). The response token fed_req_token can only be used one time.

• sync_sched

• fed_name

• fed_secret_key

• nats_hosts

• fed_req_token

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/fedml/nh_test_admin/getEncrypted"

Request Body Before Encryption:
{"passwd":"passwd","fed_rest_host":"http://charm:8080"}

Request Body:
qvh4P1y937flTE/R6GgtrN8Weu28/jCx14zBIG5zk4CEqC4+rLL/HtVvKqUthPsSVZN8BgWP39O+MKEyOsUo8w==

Response:
{"statusCode":"OK","statusString":"OK","values":{"fedInfoEncrypted":"ZwsCbdhP2GxfOgDBwJHoy61uRMZLNg7D581Cs9zWAgjwWpK2wScvgpTexpsVyilbvGThFVsWXz57n9BXY+DA1EmI+L29H+K60b1lI4v/WLr45HHCdMEDCcBAL+F3/3NcRBl5RcfgBlC4RTV6+h/75rr21lgMGxnVXlYBoUh//JpBxfJhEZyxa1gv0WVdCXDDT/M3Aq819r+6rS89jj38SYj/Hzj7pJaEHvbxe+OniH5Z90xEortLZeVdG8HE5zzqLegKpChFYFE4l60RXtdyE/fa7uY3gM7Q/yU+8SQ3Yjkvl8B5Gs7coBdgkcKNmcgiBqG4YrQSg8SCuX6RsKs4B4qV61w+AZkmt9+ipp049Hpxwu0myZ2agomcAMKdZHDv"}}

Decrypted Message Example:

Once decrypted the Federation info will contains information like in the following example. This is basically a map with a few key/ value pair. These key value pairs must be used when joining a federation. See section for details.

Decrypted JSON:
{
    "sync_sched":"m1",
    "fed_rest_url":"http://charm:8080/symetry/rest/c1/fedml/nh_test_admin/createPolicies",
    "fed_name":"nh_test_doc",
    "nats_hosts":"nats://localhost:4222",
    "fed_req_token":"FEDTOKEN38f45fe16545e80c",
}

Join a Nats Backed Federation

URL

POST /symetry/rest/{cid}/fedml/createJoin?pid={new-project-id} [body=Encrypted Map]

This REST endpoint allows the user to join an existing federation. The body is a map that is encoded to a JSON string and then encrypted using the user secret key. This encryption is necessary in order to protect sensitive information like aws access key and aws secret key that are required to be passed as part of the body.

Federation Join Request Body

The request body is composed of 2 types of key/value pairs:

• Those that come from the Admin in an encrypted form. See Decrypted Message example.

  • Mandatory Keys
• Those that relates to the new node to be created.

  • New Node Mandatory Keys

Mandatory Key / Value Pairs from Federation Admin

The following key value will be received as part of the password encrypted json message from the federation admin. They need to be added the the query body without modification.

Key	Mandatory / Optional	Description
sync_sched	Mandatory	The sync schedule, consult FedML Terminology for more details.
fed_secret_key	Mandatory	The secret key used to encrypt info exchanged between nodes in a federation.
fed_name	Mandatory	The federation id.
fed_req_token	Mandatory	The token used to verify that a join request has not expired.
nats_hosts	Mandatory	The URL of the NATS service.
nats_sec_user	Optional	The user for NATS user/password communication security. Note: this is mandatory if nats_sec_token is not used.
nats_sec_passwd	Optional	The password for NATS user/password communication security. Note: this is mandatory if nats_sec_token is not used.
nats_sec_token	Optional	The token for NATS token communication security. Note: this is mandatory if nats_sec_user and nats_sec_passwd are not used.

Request Body Key / Value Pairs

Additional key / value pairs are needed in the request body

Mandatory key	Required / Optional	Value Description
fed_local_type	Optional	The type of project to use. Supported values: cpu and gpu. The default value is cpu.

Query Parameters

Parameter	Required / Optional	Description
persist	Optional	Whether or not to persist the project. Defaults to true.
pid	Optional	Project name

HTTP Responses

HTTP Status Code	HTTP Status Message	Description
201	CREATED	Success. {"statusCode":"CREATED","statusString":" + Fed Project created with join","values":{}}
409	CONFLICT	SymetryML project already exists. {"statusCode":"CONFLICT","statusString":" + Customer [c1] already have SYMETRYML with id[r1], ","values":{}}

HTTP Response Entity

None

Sample Request/Response Fed Create Join

POST url="http://charm:8080/symetry/rest/c1/fedml/createJoin?pid=node1"

Request Body:
KjxfT4/2TpJsfwd+gAG0zAnH7r+fs7IyKrlMXNoqh5CNQjoLioBW6HjXH5hRVqEYASueMI++fmMDAEOBIQD/e/3HDeA/SVojcmzywmxcMNotH9iTpboU9KIJZVq1JW3bxAv+e2COEuI+82qrQVJ4QifuAy5TxR+B5H0GjC0x4qiDK5h+TpEDnFB1Cjdv3xQycXSud7eRwy72gtY+wi8Rey3Ku1BerIRbhRVTBaHicb2duiZTZivdx1VJKA7BbH2s...


Response:
{"statusCode":"CREATED","statusString":"Fed Project created with join","values":{}}