Standalone gateways

[muhamadazmy]

Deprecates: #1472

This story discusses the requirements and some of the implementation details of a standalone gateway: A stand alone gateway can be installed as a service by any user/farmer on the public internet and allows other users to use it to expose their private services to the public internet over allocated domain names:

• The owner of the gw does not have to be a farmer, as long as he has a valid service account
• The users of the gw still require to:
  • Reserve a name with a name contract
  • Create a contract with the service account of the gateway
• After deployment of the gateway workload, the gateway will bill the user over the service contract.

Operation of the gateway

• The gateway will expose a public API on the internet that works as follows:
  • GET / returns information about the gateway, this includes
  • Account address that is needed to create a contract (for the purpose of verification and billing)
  • Other information about the gw (I can only think now of the base gateway domain, say gateway.grid.tf)
  • POST /gateway requires a payload with the following date
  • Authentication header that include a JWT for the authetication/authorization of the request (more on the lat later)
  • Body contains the following data
    • contract-id : that is supposedly created by the user with the gw service account
    • name: this can be either a short name prefix (as reserved by a name contract) or a fqdn if the user owns a domain and want to use it (requires more work from the user side that will be explained later)
    • backends: list of valid backends
    • tls-passthrough: boolean
  • DELETE /gateway/<name>
  • This also require the JWT to verify it's requested by the owner

All requests requires a JWT the jwt token requires the following fields:

• twin-id: the twin id of the user
• iat: issued at timestamp (the server will reject requests with iat that is older than a specific time slot to prevent replay attacks

The JWT is signed with the user key. The JWT then means it can be used to authenticate the identity of that user who initiated the request.

Once authentication is passed, the user request is then processed as follows:

• fetch the contract as per the user request. We verify that:
  • contract exists
  • contract is owned by the request initiator, and is with this gatewasy service account.
  • contract is active.
• If the name is a short name (just single name with no dots in the name) then this name must be verified against the name contracts.
  • does a name contract with that name exists
  • is the name owned by the request initiator
• Once all steps above are verified, the traefik configration is written as requested, which will then proxy traffic from <name>.<gateway-domain>. to the configured backends
• If name is a fqdn (has dots in it) the name contract step is skipped and is used directly (as long it's a valid domain name)
  • A fqdn requires that the user configure his own dns to point this fqdn to the public IP of the gw.

Billing

traefic provides metrics for the domains that we can collect (and aggregate) every configurable period of time. The gw must then take care of calculating consumption over a certain period of time.

Then for each domain, we can then send consumption (or billing) reports to the contract. this should then allow hosts to get paid for providing the gw service.

Notes:

You can see above this has nothing to do with mycelium. This is because supporting mycelium is outside the scoop of the gw implementation. Mycelium supports comes free of charge by running a mycelium on the same node as the gw. Which allows backends then to use mycelium IPs.

[sameh-farouk]

• Originally for the name contract, billing was determined based on the elapsed time and tied to the name contract.
• The new specification indicates that we will now use the serviceContract for billing, while the native grid name contract remains used for only reservations.
• If a bad actor creates name contracts without actually setting up a service contact to use that name, it could lead to reserving names without payment.
• Therefore, I recommend planning ahead. Perhaps we can still bill the user for both reservation (using the elapsed time for the name contract) and consumption (based on actual usage reported by the gw to service contract).

[sameh-farouk]

Is name update something we don’t want/need to support from the beginning?

[AbdelrahmanElawady]

It should also be noted that the Service Contract requires both accounts to accept it and the service to set its required fees. That way one endpoint for adding a gateway entry won't be enough as the user will create the contracts, pass it to the service, the service will set the fees and accept then the user will accept and pass the gateway details. So, at least two requests will be made for two different endpoints to actually add an entry to the gateway service.

[renauter]

• After deployment of the gateway workload, the gateway will bill the user over the service contract.

Indeed, a service contract would be suitable to handle such gw service billing (related to some consumption). A special attention should be given to the fees definition while setting the service contract here:

https://github.com/threefoldtech/tfchain/blob/development/substrate-node/pallets/pallet-smart-contract/service_consumer_contract_flow.md#step-2-fill-contract

Because once fees are set (base_fee and variable_fee) they cannot be modified (unless creating new contract). Such configuration, with base_fee = 0 and variable_fee = max possible amount that can be billed during 1 hour, should fit the case. Also the service contract billing rules (about billing calculation and frequency) should be considered:

https://github.com/threefoldtech/tfchain/blob/development/substrate-node/pallets/pallet-smart-contract/service_consumer_contract_flow.md#step-4-bill-for-the-service