securitylib.throttling.client — Throttling client functions¶

class securitylib.throttling.client.StateChecker(counters_storage, session_storage)¶

Use this class to check the throttling state of client requests.

Parameters:	counters_storage (securitylib.throttling.common.CountersStorage) – Storage to be used for storing throttling counters. session_storage (securitylib.throttling.common.SessionStorage) – Storage to be used to store sessions.

check_state(ip, user=None, pwd=None, session_id=None, ctx='')¶

Returns the throttling state for a given request. You should call this method before processing a request to find out if a request should be blocked, if a captcha must be validated before processing the request, or if no action is needed before proceeding. You can also call this method before presenting a page to the user in order to find out what you should present: a message saying the user is blocked, a captcha for the user to fill, or neither.

Parameters:

ip (str) – The ip of the client that made the request. user (str) – The user that the client sent in his login request. (used for login attempts) pwd (str) – The password that the client sent in his login request. (used for login attempts) session_id (str) – The session_id for the client’s session. This session_id should be generated using get_random_token() or another function with the same properties, and should be stored in a cookie in the client’s browser. This session_id is to be used for thottling purposes only and so should persist even after the user logs out of the application, contrary to typical sessions. This session_id is used only for login requests and thus can be omitted for other requests. ctx – The context of the request. Use this if you want to have different throttling counters for different parts of your application. For example, you might want to separate the throttling for login requests from that of password recovery requests, meaning that a user can be blocked from sending login requests but can still try a password recovery. Each string will access different counters, so make sure that you always use the same string for a given context.

Returns:

dict – A dictionary with the requested throttling state. It always has a ‘state’ key which can have three values: ‘ok’, ‘captcha’ and ‘block’ (meaning should be obvious from the documentation above). If ‘state’ is ‘block’ there is an additional key called ‘unblock_timestamp’ which will contain a timestamp of the time when the ‘block’ state will end. This can be used to tell the client when he will be unblocked.