les server api v2.md

ServerInfo() map[string]interface{}: query server info

• minimumCapacity: minimum allowed capacity for any client
• freeClientCapacity: capacity assigned to free (unknown, non-priority) clients
• totalCapacity: total allowed capacity of simultaneously connected clients (may change dynamically during operation)
• totalConnectedCapacity: total capacity of currently connected clients
• priorityConnectedCapacity: total capacity of currently connected priority clients
• totalPriorityCapacity: total capacity of all priority clients (may exceed totalCapacity in which case priority clients might be rejected too)

SetClientParams(ids []string, tags []string, params map[string]interface{}) error: set certain parameter fields for each client whose id is in the ids list or has all tags in the tags list

• userTags: user tags assigned to the client
• capacity: priority capacity assigned to the client. Zero means non-priority status.
• pricing/timeFactor: price of one second of connection
• pricing/capacityFactor: price of one second of connection with a capacity of 1000000
  • Note: capacityFactor is convenient to use when setting pricing parameters in a batch for a group of clients. If the same capacityFactor is specified for multiple clients then the actual pricing is proportional to the individual client capacity and is automatically updated when the capacity is changed. Can also be used together with timeFactor which is independent of the client's capacity.
• pricing/requestCostFactor: price of serving requests with a total serving time of one second
• pricing/alert: send an update event to subscribers when totalAmount exceeds the given value
• pricing/periodicUpdate: send an update event to subscribers every time the given amount of cost has been accumulated
  • Note: pricing/alert and pricing/periodicUpdate are alternative alert mechanisms and cannot be used together.

Note: some tags are assigned to clients by the priority client pool automatically:

• $all is assigned to every client
• $connected is assigned to currently connected clients
• $disconnected is assigned to currently not connected clients
• $priority is assigned to priority clients
• $free is assigned to free (non-priority) clients

User tags should not start with a "$". Also note that setting parameters for multiple clients selected by tags only affects the clients having those tags at the moment of the call. Setting parameters for previously unknown clients (selected by ID) only has an effect if priority is assigned to them (capacity is non-zero). Any information about non-priority clients which are currently not connected is discarded.

Price calculation can be enabled for non-priority clients too if the server operator is interested in a theoretical value estimation of the service given away for free. In this case capacityFactor is calculated with freeClientCapacity as the current capacity. When a client is disconnected the final totalAmount can be obtained from the disconnection event. Since the client record is discarded for non-priority clients totalAmount will also start from zero even if the same client connects again.

ClientInfo(ids []string, tags []string) map[string]map[string]interface{}: returns information about a given set of clients:

• isConnected
• capacity
• hasPriority
• userTags
• pricing/totalAmount (total cost accumulated by the client according to the connection time, capacity and request cost pricing factors)

SubscribeEvents(ids []string, tags []string) (*rpc.Subscription, error): subscribe to general server events and client events for the given set of client. Event format is also map[string]interface{} with the following fields:

• totalCapacity
• totalConnectedCapacity
• priorityConnectedCapacity
• clientEvent (only if the event is client related; can be connect, disconnect or priceUpdate)
• clientId
• clientInfo (a map[string]interface{} with the same format as returned by ClientInfo)

Note: client events are generated when a client is connected, disconnected, goes into or out of priority status, its capacity has changed or it has accumulated a certain amount of cost specified in the pricing parameters. Non client related events are generated when totalCapacity has changed significantly. If totalCapacity drops under priorityConnectedCapacity then a priority client needs to be dropped or its capacity needs to be reduced. In this case an event is generated immediately and the priority pool gives a short timeframe for the endpoint to take action before selecting some clients itself and dropping them.

Thoughts about LES V2 API

• Please rename priorityAssignedCapacity to totalProrityCapacity, the latter one is more meaningful.
• Please rename tags in SetClientParams.params to costomizedTags or userTags. Since we already define some system reserved tags like $all, $priority, it will be better to make the difference.
• From the code wise:
  • the timeFactor is the time wise price
  • the requestFactor is the request cost wise price
    Could we rename these two to a more meaningful name?
• Please rename totalprice to totalExpense

Do we really need the pricing/capacityFactor?

If some priority clients apply for a big capacity but mostly idle in the connection time, I think it's fine to only charge the connection fee. Since we can let more clients overbook the capacity if some of the connected clients are idle.

And also we can set the timeFactor as a high value some that the node server can have a stable incoming guarantee.
And also we can scale the timeFactor with capacity so that the large capacity clients can be charged more.

The only reason pricing/capacityFactor makes sense is because of the batch parameter settings. If your pricing model has a factor that is proportional to capacity you can set params for all paying clients in a single batch and the API would set the actual pricing according to the capacity.

Btw now I am thinking whether I should simplify this thing and drop userTags and parameter setting for client groups. They are theoretically nice but maybe I am overcomplicating it again. So the simplifications would be:

• SetClientParams would only accept a single client ID and set params for a single client
• userTags would be dropped
• in this case pricing/capacityFactor would be unnecessary too
• ClientInfo would also accept a single client ID and return info for a single client
• another function ClientsInfo could return client info for every connected client
• subscription would also not filter by client groups, just return all client events to every subscriber (they are not so frequent after all)

I would be interested in everyone's opinion about this so if you have one please comment here whether you would like the "full" or "simplified" version.