Add bandwidth limiter

[emschwartz]

Limiting payment sizes is an important way for connectors to manage their risk. The ilp-connector should be able to put a per-account limit on the payment size. Ideally, the limit could be set to automatically adjust according to some formula for how much the user is trusted.

[michielbdejong]

makes sense, though i would say it's more to sandbox your incoming users from each other when they compete for outgoing bandwidth, than to limit a risk you run yourself as a connector?

[emschwartz]

I think it's both. As a connector you always have a tradeoff between your fulfillment risk and how long you need your "minimum message window" to be. If you want to limit how much you add to the overall hold time, it would also make sense to limit the payment size so that even if you fail to pass on some fulfillments you're not out all of your money at once. I would want to keep the payment size low, monitor my rate of failed payments, and have some alerts or automatic kill switches if the failure rate jumps (as it would if you were under attack).

[justmoon]

CONNECTOR_ACCOUNTS = {
  "arbiterry": {
    "relation": "parent",
    "plugin": "ilp-plugin-xrp-stateless",
    "assetCode": "XRP",
    "assetScale": 6,
    "middlewares": [{
      "type": "balance"
    }, {
      "type": "bandwidth",
      "direction": "outgoing",
      "options": {
        
      }
    }],
    "options": {
      "server": "btp+wss://:secret_token@example.com/btp",
      "secret": "s..."
    }
  }
}

Here is a proposal based on @emschwartz' ilp3 middleware idea.

Basically, there are modules called "middlewares" which can be applied to plugins. There are a number of built-in middlewares. Otherwise, the connector will also attempt to require a module by the provided name. (Same as backends, plugins, and stores.)

When configuring a plugin, the middlewares parameter is required, however, it may be provided an empty array to signify that no middlewares should be applied. This is useful for creating connections between your own connectors where you may not care about applying any limits or balance logic.

Middlewares are passed a store when they are instantiated and they expose methods sendMoney and sendData. When called, they receive an extra next parameter which may be used to continue the chain. Each middleware may modify the parameters or even return the call (without calling next) to fulfill or reject the packet on the spot.

Built-in middlewares include balance for keeping a balance and bandwidth for making sure the client/peer never exceeds a certain amount of payment bandwidth. Middlewares can be applied to incoming calls, outgoing calls or to both directions (default).

Some of the internal connector components could also be turned into middleware. No super-huge benefit to that, but it's kinda neat.

All credit to @emschwartz! Good idea worth adopting.

[dappelt]

Great! This is perfect for getting a basic XRP paychan connector going. Is this already somewhere implemented?

[michielbdejong]

In cases where my outgoing peer is obviously late, as a service to my customers, I can eat the loss and send my customer a timely reject, but that would be an active decision. ilp-connector does not currently do this but ilp-plu-pa-cha-fra does.

The maximum loss per customer, per time it happens, is already limited by maxUnsecuredBalance. So maybe the thing to limit would be how often ilp-plu-pa-cha-fra cancels an incoming transfer from a specific stateless client?

A limit on incoming transfer amount could make it so that a customer cannot spend their maxUnsecuredBalance in a single payment, but that does not mean it would limit your exposure to the fulfillment risk. Suppose a customer's maxUnsecuredBalance is 10, and you use this proposed feature to additionally limit payment size to 1. That means that instead of one payment with amount 10, the customer can now do ten payments in parallel, and if they all fail, you still lose that customer's entire maxUnsecuredBalance before you get a chance to throttle them. So it's easier to just set maxUnsecuredBalance low enough, and then throttle how often ilp-plu-pa-cha-fra actively cancels an incoming transfer?

[dappelt]

The purpose of the bandwidth limiter is to mitigate the risk that a (new) customer does not give the connector a claim once the payment is fulfilled (remember that XRP paychans are unconditional). It does not aim to mitigate the fulfillment risk.

Suppose a customer's maxUnsecuredBalance is 10, and you use this proposed feature to additionally limit payment size to 1.

The bandwidth limiter does not introduce an additional limit. Think of it rather as dynamically increasing maxUnsecuredBalance with each received claim.

[michielbdejong]

But in #400 (comment), @emschwartz stated that he wants to use it to allow for shorter message windows?

And dynamically increasing maxUnsecuredBalance would require disconnecting and reconnecting the plugin, right? The LPI does not provide a plugin.updateOptions method.

So at the very least, max payment size and maxUnsecuredBalance have overlapping purposes?