GS2-Limit Transaction Actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-Limit adds to it.

The transaction actions of GS2-Limit address one counter, identified by the combination of namespace, user, limit model, and counter name.

Counting up and down are one row because both are written as a pure increment on the same value; mixing them is fine. The result is judged against the total after combining. The count cannot go below zero and cannot exceed the limit set on the limit model, so a count up that fits on its own can still be rejected when combined with another one.

Count ups with differing upper limits cannot be placed against the same counter. Adding them up while the limits disagree would either drop a stricter limit or have a permissive increment rejected by a stricter one, so count ups with differing maxValue against one counter are rejected when the transaction is issued. Specify them separately.

Deleting a counter removes the counter itself rather than changing its value, so it cannot sit alongside anything else on that counter. Split the transaction where you want to reset a counter and then start counting again. Turning on sequential execution mode (enableSequentialExecution or TransactionSettingV2) lets a delete sit alongside a count up. The order is not yours to choose: counting up is a consume action and the delete is an acquire action, so the delete always runs last and removes whatever was just counted. A delete cannot be used to start a counter fresh and then count from zero in the same transaction.

A counter is a state (how many times something has been done), so its threshold does not scale with the quantity by default. What scales is the paired count up. Setting multiplyValueSpecifyingQuantity to true explicitly makes the threshold add up and scale with the quantity. Even then it is added up only where adding it up makes the check stricter. With greater and greaterEqual a larger threshold is harder to satisfy, so repeating the same check tightens it, and multiplyValueSpecifyingQuantity scales it with the purchased quantity. With less and lessEqual a larger threshold is easier to satisfy, so adding up would let a limit be evaded by repeating the check or by raising the quantity; these are only gathered into one and the quantity does not scale them. equal and notEqual turn into a different claim when added up, so they are only gathered into one as well.

Verify actions look at the counter as of the start of the transaction. You cannot verify a count that is reached by the same transaction.

Take care with nested transactions

Counting up and down are safe across a nested transaction: they are applied together as one update whichever route they arrive by.

Deleting a counter is not. A deletion arriving from the inside while the same counter is counted from the outside makes the transaction fail. Sequential execution mode removes this failure where the count is a count up: the inner transaction now runs inside the same sequential section as the outer one, and a count up followed by the delete composes instead of colliding. Where the delete runs first and a count down follows, the two still cannot be combined and the transaction fails.

If you want to avoid these restrictions

Counting down and deleting a counter are acquire actions; counting up is a consume action. Turning acquireActionUseJobQueue on clears a collision between a deletion and a count down, but a deletion together with a count up needs enableAtomicCommit turned off.

Concurrency and retries

Counting up and down do not conflict however many concurrent requests overlap, as long as the result stays within range. A conflict (409) is returned when concurrent count ups together exceed the limit, or when concurrent count downs together take the count below zero; retrying re-evaluates against the latest count.

A counter is reset on a schedule. A request that lands exactly on a reset boundary may return a conflict (409); retrying after the reset has settled will succeed.

Verify Action

Gs2Limit:VerifyCounterByUserId

Verify Counter value by User ID

Verifies that the specified user’s counter value satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual.

Quantity specification supported: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Limit:VerifyCounterByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "limitName": "[string]Usage Limit Model Name",
        "counterName": "[string]Counter Name",
        "verifyType": "[string]Type of verification",
        "count": "[int]Count Value",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Limit:VerifyCounterByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  limitName: "[string]Usage Limit Model Name"
  counterName: "[string]Counter Name"
  verifyType: "[string]Type of verification"
  count: "[int]Count Value"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("limit").verify.verify_counter_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    limitName="[string]Usage Limit Model Name",
    counterName="[string]Counter Name",
    verifyType="[string]Type of verification",
    count="[int]Count Value",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Consume Action

Gs2Limit:CountUpByUserId

Count-up by User ID

Increments the specified user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Limit:CountUpByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "limitName": "[string]Usage Limit Model Name",
        "counterName": "[string]Counter Name",
        "userId": "[string]User ID",
        "countUpValue": "[int]Amount to count up",
        "maxValue": "[int]Maximum value allowed to count up",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Limit:CountUpByUserId
request:
  namespaceName: "[string]Namespace name"
  limitName: "[string]Usage Limit Model Name"
  counterName: "[string]Counter Name"
  userId: "[string]User ID"
  countUpValue: "[int]Amount to count up"
  maxValue: "[int]Maximum value allowed to count up"
  timeOffsetToken: "[string]Time offset token"

transaction.service("limit").consume.count_up_by_user_id({
    namespaceName="[string]Namespace name",
    limitName="[string]Usage Limit Model Name",
    counterName="[string]Counter Name",
    userId="[string]User ID",
    countUpValue="[int]Amount to count up",
    maxValue="[int]Maximum value allowed to count up",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Limit:CountDownByUserId

Count-down by User ID

Decrements the specified user’s counter by the specified count-down value. The counter value will not go below 0.

Quantity specification supported: YES

Reversible action: YES

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Limit:CountDownByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "limitName": "[string]Usage Limit Model Name",
        "counterName": "[string]Counter Name",
        "userId": "[string]User ID",
        "countDownValue": "[int]Amount to count down",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Limit:CountDownByUserId
request:
  namespaceName: "[string]Namespace name"
  limitName: "[string]Usage Limit Model Name"
  counterName: "[string]Counter Name"
  userId: "[string]User ID"
  countDownValue: "[int]Amount to count down"
  timeOffsetToken: "[string]Time offset token"

transaction.service("limit").acquire.count_down_by_user_id({
    namespaceName="[string]Namespace name",
    limitName="[string]Usage Limit Model Name",
    counterName="[string]Counter Name",
    userId="[string]User ID",
    countDownValue="[int]Amount to count down",
    timeOffsetToken="[string]Time offset token",
})

Gs2Limit:DeleteCounterByUserId

Delete Counter by User ID

Deletes the specified user’s counter, resetting the usage count. This effectively removes the limit restriction for this counter, allowing the user to start counting from 0 again.

Quantity specification supported: NO

Reversible action: NO

• Format:
• JSON
• YAML
• GS2-Script

{
    "action": "Gs2Limit:DeleteCounterByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "limitName": "[string]Usage Limit Model Name",
        "userId": "[string]User ID",
        "counterName": "[string]Counter Name",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Limit:DeleteCounterByUserId
request:
  namespaceName: "[string]Namespace name"
  limitName: "[string]Usage Limit Model Name"
  userId: "[string]User ID"
  counterName: "[string]Counter Name"
  timeOffsetToken: "[string]Time offset token"

transaction.service("limit").acquire.delete_counter_by_user_id({
    namespaceName="[string]Namespace name",
    limitName="[string]Usage Limit Model Name",
    userId="[string]User ID",
    counterName="[string]Counter Name",
    timeOffsetToken="[string]Time offset token",
})