Feature/rest server quota

docs/API/QuotaManagerClass.md

@@ -0,0 +1,148 @@
+---
+id: QuotaManagerClass
+title: QuotaManager
+---
+
+
+The `4D.QuotaManager` class provides you with an interface to configure and monitor some usage limits you apply to your 4D application. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. 
+
+
+`4D.QuotaManager` objects can be instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object.
+
+
+<details><summary>History</summary>
+
+|Release|Changes|
+|---|---|
+|21 R4|Class added|
+
+</details>
+
+
+
+### QuotaManager Object
+
+
+4D.QuotaManager objects provide the following properties:
+
+||
+|---|
+|[<!-- INCLUDE #QuotaManagerClass.currentValues.Syntax -->](#currentvalues)<br/><!-- INCLUDE #QuotaManagerClass.defaultcurrentValuesEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.defaultEntitySetTimeout.Syntax -->](#defaultentitysettimeout)<br/><!-- INCLUDE #QuotaManagerClass.defaultEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.maxEntitySetTimeout.Syntax -->](#maxentitysettimeout)<br/><!-- INCLUDE #QuotaManagerClass.maxEntitySetTimeout.Summary -->|
+|[<!-- INCLUDE #QuotaManagerClass.nbEntitySets.Syntax -->](#nbentitysets)<br/><!-- INCLUDE #QuotaManagerClass.nbEntitySets().Summary -->|
+
+
+
+<!-- REF QuotaManagerClass.currentValues.Desc -->
+## .currentValues
+
+<!-- REF #QuotaManagerClass.currentValues.Syntax -->**currentValues** : Object<!-- END REF -->
+
+#### Description
+
+The `.currentValues` property contains <!-- REF #QuotaManagerClass.currentValues.Summary -->the current values related to the defined quotas properties<!-- END REF -->. This object is automatically updated by the server. 
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.defaultEntitySetTimeout.Desc -->
+## .defaultEntitySetTimeout
+
+<!-- REF #QuotaManagerClass.defaultEntitySetTimeout.Syntax -->**defaultEntitySetTimeout** : Integer<!-- END REF -->
+
+#### Description
+
+The `.defaultEntitySetTimeout` property contains <!-- REF #QuotaManagerClass.defaultEntitySetTimeout.Summary -->the default inactivity timeout for REST entity sets stored in memory during the current session (in seconds)<!-- END REF -->.
+
+By default, this value is 2 hours (7200 seconds). It can also be defined at the entity set creation using the [`$timeout` REST API](../REST/$timeout.md). 
+
+You can change this value dynamically using the [`quotas.defaultEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterwards in the session (existing entity set default timeout values are not modified). 
+
+:::note
+
+If you define a value higher than the `maxEntitySetTimeout` property value, it will be aligned with the `maxEntitySetTimeout` value. 
+
+:::
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+Session.quotas.defaultEntitySetTimeout:=1200
+```
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.maxEntitySetTimeout.Desc -->
+## .maxEntitySetTimeout
+
+<!-- REF #QuotaManagerClass.maxEntitySetTimeout.Syntax -->**maxEntitySetTimeout** : Integer<!-- END REF -->
+
+#### Description
+
+The `.maxEntitySetTimeout` property contains <!-- REF #QuotaManagerClass.maxEntitySetTimeout.Summary -->the maximum inactivity timeout value for REST entity sets stored in memory during the current session (in seconds)<!-- END REF -->.
+
+You can set this value using the [`quotas.maxEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterward in the session (existing entity set maximum timeout values are not modified). 
+
+Once the `.maxEntitySetTimeout` property is set, any entity set created afterward in the session could not have a timeout value longer than the `.maxEntitySetTimeout` value.
+
+For example, assuming the maximum inactivity timeout is set to 40 minutes (2400 seconds), if an entity set is created with a required timeout which exceeds the maximum value:
+
+```
+http://127.0.0.1/rest/People?$filter=ID>=4&$method=entityset&$timeout=3000
+```
+
+... then the timeout defined in the request is ignored and the entity set will be released after 40 minutes if not used during this period of time.
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+Session.quotas.maxEntitySetTimeout:=2400
+```
+
+
+<!-- END REF -->
+
+
+<!-- REF QuotaManagerClass.nbEntitySets.Desc -->
+## .nbEntitySets
+
+<!-- REF #QuotaManagerClass.nbEntitySets.Syntax -->**nbEntitySets** : Integer<!-- END REF -->
+
+#### Description
+
+The `.nbEntitySets` property contains <!-- REF #QuotaManagerClass.nbEntitySets.Summary -->the maximum number of REST entity sets allowed in memory for the current session (in seconds)<!-- END REF -->.
+
+By default, there is no limit for entity sets [stored in memory by REST requests](../REST/$info.md) (the value is 0). You can set a limit to control the server payload for a specific session.
+
+When the maximum number of allowed entity sets is reached, a REST request that need to create an entity set will get a [**429** HTTP status code and an error response](../REST/REST_requests.md#rest-status-and-response), until at least one entity set is released. You can release an entity set from the cache using the [`$release` REST command](../REST/$entityset.md#entitysetrelease). 
+
+You cannot pass a value <=0 (an error is generated in this case). To reset the property value for the session, pass *undefined*. 
+
+
+#### Example
+
+In some 4D code in a REST process:
+
+```4d
+	//max 50 entity sets
+Session.quotas.nbEntitySets:=50
+```
+
+<!-- END REF -->
+
+
+
+

docs/API/SessionClass.md

@@ -53,6 +53,7 @@ All session types can handle privileges, but only the code executed in a **web c
 |[<!-- INCLUDE #SessionClass.info.Syntax -->](#info)<br/><!-- INCLUDE #SessionClass.info.Summary -->|
 |[<!-- INCLUDE #SessionClass.isGuest().Syntax -->](#isguest)<br/><!-- INCLUDE #SessionClass.isGuest().Summary -->|
 |[<!-- INCLUDE #SessionClass.promote().Syntax -->](#promote)<br/><!-- INCLUDE #SessionClass.promote().Summary -->|
+|[<!-- INCLUDE #SessionClass.quotas.Syntax -->](#quotas)<br/><!-- INCLUDE #SessionClass.quotas.Summary -->|
 |[<!-- INCLUDE #SessionClass.restore().Syntax -->](#restore)<br/><!-- INCLUDE #SessionClass.restore().Summary -->|
 |[<!-- INCLUDE #SessionClass.setPrivileges().Syntax -->](#setprivileges)<br/><!-- INCLUDE #SessionClass.setPrivileges().Summary -->|
 |[<!-- INCLUDE #SessionClass.storage.Syntax -->](#storage)<br/><!-- INCLUDE #SessionClass.storage.Summary -->|
@@ -571,6 +572,8 @@ Since `.info` is a computed property, it is recommended to call it once and then
 
 :::
 
+This property is **read only**.
+
 
 <!-- END REF -->
 
@@ -718,6 +721,61 @@ End if
 <!-- END REF -->
 
 
+<!-- REF SessionClass.quotas.Desc -->
+## .quotas
+
+<details><summary>History</summary>
+
+|Release|Changes|
+|---|---|
+|21 R4|Added|
+
+</details>
+
+<!-- REF #SessionClass.quotas.Syntax -->**.quotas** : 4D.QuotaManager<!-- END REF -->
+
+#### Description
+
+
+The `.quotas` property contains <!-- REF #SessionClass.quotas.Summary -->a `4D.QuotaManager` object with current values and set values for server thresholds in the current session<!-- END REF -->. Server thresholds are used to control the requests to the server and help preventing excessive use of resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)).
+
+This property is **read only**.
+
+The following properties of the `4D.QuotaManager` object are available for the session:
+
+|Property||Type|Writable|Description|
+|---|---|---|---|---|
+|[nbEntitySets](./QuotaManagerClass.md#nbentitysets)||Integer|yes|Maximum allowed number of entity sets in server's memory|
+|[defaultEntitySetTimeout](./QuotaManagerClass.md#defaultentitysettimeout) ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)|
+|[maxEntitySetTimeout](./QuotaManagerClass.md#maxentitysettimeout) ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)|
+|currentValues||Object|no||
+||nbEntitySets|Integer|no|Number of entity sets currently in memory|
+
+When you modify a value, it is immediately taken into account by the server (no need to restart) and will be applied to further REST requests. 
+
+:::tip Related blog post
+
+[Make your REST server at the top of its game ... Forget throttling or crashing and tune yourself the memory usage](https://blog.4d.com/make-your-rest-server-at-the-top-of-its-game-forget-throttling-or-crashing-and-tune-yourself-the-memory-usage).
+
+:::
+
+#### Example
+
+```4d
+   //set the maximum number of entity sets in memory
+   //for the session to 50
+Session.quotas.nbEntitySets:=50
+```
+
+<!-- END REF -->
+
+
+#### See also
+
+[QuotaManager class](./QuotaManagerClass.md)
+
+
+
 <!-- REF SessionClass.restore().Desc -->
 ## .restore()
 

docs/Notes/updates.md

@@ -11,7 +11,13 @@ Read [**What’s new in 4D 21 R4**](https://blog.4d.com/whats-new-in-4d-21-r4/),
 
 - Multi-level list style sheets are now [supported in 4D Write Pro Interface](../WritePro/writeprointerface.md#multi-level-style-sheets), allowing users to create and manage structured multi-level lists directly from the toolbar and sidebar.
 - New [`defer`](../commands/defer) command to declare some code to be always executed at method or function exit; new [`Deferred formulas`](../commands/deferred-formulas) command to get the list of deferred formulas. 
+- New session `.quotas` property to configure thresholds for sessions. 
+- New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server.
+- New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from server cache.
 
+#### Behavior changes
+
+- The **`GET /Employee/$entityset/<entitySetID>?$method=release`** REST syntax is **deprecated** and should no longer be used. To delete entity sets, you must now use [`/$entityset/$release` with a POST verb](./$entityset.md).
 
 
 ## 4D 21 R3

docs/REST/$entityset.md

@@ -12,6 +12,7 @@ After [creating an entity set]($method.md#methodentityset) by using `$method=ent
 |---|---|---|
 |[**$entityset/\{entitySetID\}**](#entitysetentitysetid)|`/People/$entityset/0ANUMBER`|Retrieves an existing entity set|
 |[**$entityset/\{entitySetID\}?$logicOperator...&$otherCollection**](#entitysetentitysetidlogicoperatorothercollection)|`/Employee/$entityset/0ANUMBER?$logicOperator=AND&$otherCollection=0ANUMBER`|Creates a new entity set from comparing existing entity sets|
+|[**$entityset/$release**](#entitysetrelease)|`/Employee/$entityset/$release`|Releases one or more existing entity sets from the 4D Server's cache|
 
 
 
@@ -98,3 +99,29 @@ If there is an intersection, this query returns true. Otherwise, it returns fals
 In the following example we create a new entity set that combines all the entities in both entity sets:
 
 ` GET  /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7?$logicOperator=OR&$otherCollection=C05A0D887C664D4DA1B38366DD21629B&$method=entityset`
+
+
+## $entityset/$release
+
+Releases on or more existing entity set(s) stored in [4D Server's cache](./$info.md).
+
+### Description  
+
+You can use this command to release a collection of entity sets, which you created using [`$method=entityset`](#methodentityset), from 4D Server's cache. 
+
+### Example  
+
+Release two entity sets from the server's cache:
+
+`POST  /rest/Employee/$entityset/$release`
+
+The body must contain a collection with the entity sets ids to release:
+
+**POST data**:
+
+```json
+[
+"552AE0C8329045FDB65A8C151AEBC532", "9D0617688D7540C090D7675CAF21D7C8"
+]
+```
+

docs/REST/$info.md

@@ -12,27 +12,28 @@ When you call this request for your project, you retrieve information in the fol
 |---|---|---|
 |cacheSize|	Number	|4D Server's cache size.|
 |usedCache	|Number	|How much of 4D Server's cache has been used.|
-|entitySetCount	|Number	|Number of entity selections.|
-|entitySet	|Collection|A collection in which each object contains information about each entity selection.|
+|entitySetCount	|Number	|Number of entity sets.|
+|entitySet	|Collection|A collection in which each object contains information about each entity set.|
 |ProgressInfo|	Collection	|A collection containing information about progress indicator information.|
 |sessionInfo|	Collection	|A collection in which each object contains information about each user session.|
 |privileges|	Object	|An object with a "privileges" property (collection of objects). Each object of the collection has a "privilege" property with a privilege name of the user session as value.|
 
 
 ### entitySet  
-For each entity selection currently stored in 4D Server's cache, the following information is returned:
+
+For each entity set currently stored in 4D Server's cache, the following information is returned:
 
 
 |Property|	Type|	Description|
 |---|---|---|
 |id|Text|	A UUID that references the entity set.|
 |dataClass|Text	|Name of the dataclass.|
-|selectionSize|	Number|	Number of entities in the entity selection.|
+|selectionSize|	Number|	Number of entities in the entity set.|
 |sorted|Boolean|Returns true if the set was sorted (using `$orderby`) or false if it's not sorted.|
 |refreshed|Date|When the entity set was created or the last time it was used.|
-|expires|Date|When the entity set will expire (this date/time changes each time when the entity set is refreshed). The difference between refreshed and expires is the timeout for an entity set. This value is either two hours by default or what you defined using `$timeout`.
+|expires|Date|When the entity set will expire (this date/time changes each time when the entity set is refreshed). The difference between refreshed and expires is the timeout for an entity set. This value is either two hours by default or what you defined using `$timeout`. It can also be modified for the session through the [`Session.quotas`](../API/SessionClass.md#quotas) property. |
 
-For information about how to create an entity selection, refer to `$method=entityset`. If you want to remove the entity selection from 4D Server's cache, use `$method=release`.
+For information about how to create an entity set, refer to [`$method=entityset`](./$method.md#methodentityset). If you want to remove the entity selection from 4D Server's cache, use [`$entityset/$release`](./$entityset.md#entitysetrelease).
 
 >4D also creates its own entity selections for optimization purposes, so the ones you create with `$method=entityset` are not the only ones returned.
 

docs/REST/$method.md

@@ -9,16 +9,13 @@ This parameter allows you to define the operation to execute with the returned e
 
 |Syntax|Example|Description|
 |---|---|---|
-|[**$method=delete**](#methoddelete)|`POST /Employee?$filter="ID=11"& $method=delete`|Deletes the current entity, entity collection, or entity selection|
+|[**$method=delete**](#methoddelete)|`POST /Employee?$filter="ID=11"& $method=delete`|Deletes the current entity, entity collection, or entity set|
 |[**$method=entityset**](#methodentityset)|`GET /People/?$filter="ID>320"& $method=entityset& $timeout=600`|Creates an entity set in 4D Server's cache based on the collection of entities defined in the REST request|
-|[**$method=release**](#methodrelease)|`GET /Employee/$entityset/<entitySetID>?$method=release`|Releases an existing entity set stored in 4D Server's cache|
 |[**$method=subentityset**](#methodsubentityset)|`GET /Company(1)/staff?$expand=staff& $method=subentityset&   $subOrderby=lastName ASC`|Creates an entity set based on the collection of related entities defined in the REST request|
 |[**$method=update**](#methodupdate)|`POST /Person/?$method=update`|Updates and/or creates one or more entities|
 
 
 
-
-
 ## $method=delete
 
 Deletes the current entity, entity collection, or entity selection (created through REST)
@@ -60,10 +57,16 @@ Creates an entity set in 4D Server's cache based on the collection of entities d
 
 ### Description   
 
-When you create a collection of entities in REST, you can also create an entity set that will be saved in 4D Server's cache. The entity set will have a reference number that you can pass to `$entityset/\{entitySetID\}` to access it. By default, it is valid for two hours; however, you can modify that amount of time by passing a value (in seconds) to $timeout.
+When you create a collection of entities in REST, you can also create an entity set that will be saved in 4D Server's cache. The entity set will have a reference number that you can pass to `$entityset/\{entitySetID\}` to access it. By default, it is valid for two hours; however, you can modify that amount of time by passing a value (in seconds) to [`$timeout`](./$timeout.md). It can also be modified for the session through the [`Session.quotas`](../API/SessionClass.md#quotas) property.
 
 If you have used `$savedfilter` and/or `$savedorderby` (in conjunction with `$filter` and/or `$orderby`) when you created your entity set, you can recreate it with the same reference ID even if it has been removed from 4D Server's cache.
 
+:::note
+
+By default, you can create as many entity sets as you want. However, the total number of entity sets in the 4D Server cache can be limited for a session through the [`Session.quotas`](../API/SessionClass.md#quotas) property. 
+
+:::
+
 ### Example
 
 To create an entity set, which will be saved in 4D Server's cache for two hours, add `$method=entityset` at the end of your REST request:
@@ -86,41 +89,6 @@ __ENTITYSET: "http://127.0.0.1:8081/rest/Employee/$entityset/9718A30BF61343C7963
 
 
 
-## $method=release
-
-Releases an existing entity set stored in 4D Server's cache.
-
-### Description  
-
-You can release an entity set, which you created using [`$method=entityset`](#methodentityset), from 4D Server's cache.
-
-### Example  
-
-Release an existing entity set:
-
-`GET  /rest/Employee/$entityset/4C51204DD8184B65AC7D79F09A077F24?$method=release`
-
-#### Response:
-
-If the request was successful, the following response is returned:
-
-```json
-{
-    "ok": true
-}
-If the entity set wasn't found, an error is returned:
-
-{
-    "__ERROR": [
-        {
-            "message": "Error code: 1802\nEntitySet  \"4C51204DD8184B65AC7D79F09A077F24\" cannot be found\ncomponent:  'dbmg'\ntask 22, name: 'HTTP connection handler'\n",
-            "componentSignature": "dbmg",
-            "errCode": 1802
-        }
-    ]
-}
-```
-
 
 ## $method=subentityset