The purpose of this feature is to allow administrators to selectively control which API calls are throttled, without having to rebuild and deploy a new version every time a throttle is changed.

...

CREATE TABLE 'THROTTLEDTHROTTLE_CALLSRULES'(
	'THROTTLE_ID' int(20) PRIMARY KEY,              --id of the throttle rule
	'NORMALIZED_URI' varchar(256) NOT NULL,        --normalized api URL, numbers such as {id} replaced with #
	'MAX_LOCKSCALLS' int(20) NOT NULL,                   --maximum number of lockscalls per user per timeURI per blockbin
	'LOCKCALL_PERIOD_TIMEOUTIN_SECONDS' int(20) NOT NULL,        --durationbin of each time block in seconds
	'THROTTLE_EXPIRATION' bigint(20) DEFAULT NULL,  --optional expiration of the rule in unix timestamp. maybe not necessary? time in which a user is allowed to make MAX_CALLS API calls.
	'TIMESTAMP' TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP --Timestamp of when the row was changed. used as an etag for migration
	UNIQUE ('NORMALIZED_CALL')
)

...

UserThrottleFilter will have a in-memory cached version of this table. It would periodically check the THROTTLED_CALLS table and update its cached version to reflect the information in the database.

The cached in memory version(refreshed every 5 minutes) will be a Map from the normalized URI to a pair of values for maxLocks and lockTimeoutSeconds. 

...

Throttle Logic

When an request comes in, it must first pass the concurrent throttle, then the frequncy throttle, then the service specific throttle.

For the service specific throttle, the request URI will be normalized using normalizeMethodSignature() in AccessRecordUtils of the Synapse-Warehouse-Records project (copy it overmove/refactor?).

Once normalized, the URI is compared to the cached throttle rules to see if it is being throttled. 

• If it is not throttled, proceed to next filter.
• If it is throttled , attempt to get a lock from the semaphore. The key used for the semaphore will be the userID + normalizedThrottledCall.
  • If a lock can be successfully acquired, proceed to next filter.
  • If we can not get a lock, block the request and return a HTTP 429 error code. otherwise proceed with the other filters.

Services

These services make updating rules more convenient.

Administrators could also just directly update the SQL table. 

...

• and the user has exceeded the limit. Return 503 error code (will be changed to 429 when clients are able to handle this code).

Services

No services. Administrators will update the table in MySQL.

Potential problems

If there are many calls being throttled, the throttle could potentially use up a lot of memory. With N throttled calls and M users, the throttle's map for call counts could have up to M x N entires. Additionally, the map will not remove entries for users that are are no longer making calls so memory will not be freed until an administrator calls clearAllLocks().

...