diff --git a/docs/API/QuotaManagerClass.md b/docs/API/QuotaManagerClass.md new file mode 100644 index 00000000000000..dac7c5f63e38c9 --- /dev/null +++ b/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. + + +
History + +|Release|Changes| +|---|---| +|21 R4|Class added| + +
+ + + +### QuotaManager Object + + +4D.QuotaManager objects provide the following properties: + +|| +|---| +|[](#currentvalues)
| +|[](#defaultentitysettimeout)
| +|[](#maxentitysettimeout)
| +|[](#nbentitysets)
| + + + + +## .currentValues + +**currentValues** : Object + +#### Description + +The `.currentValues` property contains the current values related to the defined quotas properties. This object is automatically updated by the server. + + + + + + +## .defaultEntitySetTimeout + +**defaultEntitySetTimeout** : Integer + +#### Description + +The `.defaultEntitySetTimeout` property contains the default inactivity timeout for REST entity sets stored in memory during the current session (in seconds). + +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 +``` + + + + + + +## .maxEntitySetTimeout + +**maxEntitySetTimeout** : Integer + +#### Description + +The `.maxEntitySetTimeout` property contains the maximum inactivity timeout value for REST entity sets stored in memory during the current session (in seconds). + +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 +``` + + + + + + +## .nbEntitySets + +**nbEntitySets** : Integer + +#### Description + +The `.nbEntitySets` property contains the maximum number of REST entity sets allowed in memory for the current session (in seconds). + +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 +``` + + + + + + diff --git a/docs/API/SessionClass.md b/docs/API/SessionClass.md index 04140e68c650c3..43853194a25773 100644 --- a/docs/API/SessionClass.md +++ b/docs/API/SessionClass.md @@ -53,6 +53,7 @@ All session types can handle privileges, but only the code executed in a **web c |[](#info)
| |[](#isguest)
| |[](#promote)
| +|[](#quotas)
| |[](#restore)
| |[](#setprivileges)
| |[](#storage)
| @@ -571,6 +572,8 @@ Since `.info` is a computed property, it is recommended to call it once and then ::: +This property is **read only**. + @@ -718,6 +721,61 @@ End if + +## .quotas + +
History + +|Release|Changes| +|---|---| +|21 R4|Added| + +
+ +**.quotas** : 4D.QuotaManager + +#### Description + + +The `.quotas` property contains a `4D.QuotaManager` object with current values and set values for server thresholds in the current session. 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 +``` + + + + +#### See also + +[QuotaManager class](./QuotaManagerClass.md) + + + ## .restore() diff --git a/docs/Notes/updates.md b/docs/Notes/updates.md index f520d07c2a4bad..5398c46de53954 100644 --- a/docs/Notes/updates.md +++ b/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/?$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 diff --git a/docs/REST/$entityset.md b/docs/REST/$entityset.md index cf88b6ac9739ea..e5330a59ced842 100644 --- a/docs/REST/$entityset.md +++ b/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" +] +``` + diff --git a/docs/REST/$info.md b/docs/REST/$info.md index 6b44ea8919d83d..1f4eac250775e9 100644 --- a/docs/REST/$info.md +++ b/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. diff --git a/docs/REST/$method.md b/docs/REST/$method.md index 81c619bc05a291..9e7be729e0bb27 100644 --- a/docs/REST/$method.md +++ b/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/?$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 diff --git a/docs/REST/$timeout.md b/docs/REST/$timeout.md index 0463f12e19b760..2f6be153cae4ea 100644 --- a/docs/REST/$timeout.md +++ b/docs/REST/$timeout.md @@ -14,6 +14,12 @@ Once the timeout has been defined, each time an entity set is called upon (by us If an entity set is removed and then recreated using `$method=entityset` along with [`$savedfilter`]($savedfilter.md), the new default timeout is 10 minutes regardless of the timeout you defined when calling `$timeout`. +:::note + +The timeout can also be modified for a session using the [`Session.quotas`](../API/SessionClass.md#quotas) property. + +::: + ## Example In our entity set that we're creating, we define the timeout to 20 minutes: diff --git a/docs/language-legacy/Processes/session.md b/docs/language-legacy/Processes/session.md index 540214e6309334..aaa2b1a57004dd 100644 --- a/docs/language-legacy/Processes/session.md +++ b/docs/language-legacy/Processes/session.md @@ -34,7 +34,7 @@ The `Session` command returns the `Sessio Depending on the process from which the command is called, the current session can be: -- a web session (when [scalable sessions are enabled](../../WebServer/sessions.md#enabling-web-sessions)), +- a web session (when [scalable sessions are enabled](../../WebServer/sessions.md#enabling-web-sessions)), which includes REST sessions, - a remote user session (on the server or on the client), - a stored procedures session, - a standalone session. @@ -43,6 +43,12 @@ For more information, see the [Session types](../../API/SessionClass.md#session- The command returns *Null* if it is called in a web process and scalable sessions are disabled on the web server. +:::note + +There is always at least one REST session on the server, even if [scalable sessions are disabled](../../WebServer/sessions.md#enabling-web-sessions). Thus, the `Session` command always returns a REST session object when called from a REST process. + +::: + ### Web sessions The `Session` object of web sessions is available from any web process: diff --git a/docs/preprocessing.conf b/docs/preprocessing.conf index 17789410c6d96b..964d8ab9ae72e6 100644 --- a/docs/preprocessing.conf +++ b/docs/preprocessing.conf @@ -1,48 +1,48 @@ -Transporter -POP3Transporter -IMAPNotifier -IMAPTransporter -SMTPTransporter -MailAttachment -Email -File -ZipFile -ZipFolder -ZipArchive -Document -Folder -CryptoKey -Function -Formula -Method +Class Collection +CryptoKey +DataClass +DataStore Directory -Signal -Session -SystemWorker +Document +Email Entity EntitySelection -DataClass -DataStore -Class -ClassStore -WebServer +File +FileHandle +Folder +Formula +Function HTTPAgent HTTPRequest -FileHandle -WebSocket -WebSocketServer -WebSocketConnection -WebForm -WebFormItem +IMAPNotifier +IMAPTransporter IncomingMessage +MailAttachment +Method OutgoingMessage -UDPEvent -UDPSocket +POP3Transporter +QuotaManager +Session +Signal +SMTPTransporter +SystemWorker TCPConnection TCPEvent TCPListener +Transporter +UDPEvent +UDPSocket Vector +WebForm +WebFormItem +WebServer +WebSocket +WebSocketConnection +WebSocketServer +ZipArchive +ZipFile +ZipFolder