AWS neptune documentation change
Summary
Added documentation on transaction timeouts, commit/rollback behavior for script-based and bytecode sessions, server-side cleanup mechanisms, and updated TinkerPop references.
Security assessment
The change adds guidance on managing transaction timeouts, lock contention, and orphaned transaction cleanup, which can prevent resource exhaustion and improve application stability, but no specific security vulnerability or incident is cited.
Diff
diff --git a/neptune/latest/userguide/access-graph-gremlin-transactions.md b/neptune/latest/userguide/access-graph-gremlin-transactions.md index 72b978698..4c51f9add 100644 --- a//neptune/latest/userguide/access-graph-gremlin-transactions.md +++ b//neptune/latest/userguide/access-graph-gremlin-transactions.md @@ -5 +5 @@ -SessionlessSession-bound requests +SessionlessSession-bound requestsCommit and rollback timeouts @@ -83 +83,7 @@ For scripts, the implication is that there is no need to concatenate together al -For bytecode, after TinkerPop `3.5.x`, the transaction can be explicitly controlled and the session managed transparently. Gremlin Language Variants (GLV) support Gremlin's `tx()` syntax to `commit()` or `rollback()` a transaction as follows: +For script-based sessions, closing the client with `client.close()` commits the transaction. There is no explicit rollback command available in script-based sessions. To force a rollback, you can cause the transaction to fail by issuing a query such as `g.inject(0).fail('rollback')` before closing the client. + +###### Note + +A query like `g.inject(0).fail('rollback')`, used to intentionally throw an error to force a rollback, produces an exception on the client. Catch and discard the resulting exception before closing the client. + +For bytecode, the transaction can be explicitly controlled and the session managed transparently. Gremlin Language Variants (GLV) support Gremlin's `tx()` syntax to `commit()` or `rollback()` a transaction as follows: @@ -105 +111 @@ For bytecode, after TinkerPop `3.5.x`, the transaction can be explicitly control -Although the example above is written in Java, you can also use this `tx()` syntax in Python, Javascript and .NET. +Although the example above is written in Java, you can also use this `tx()` syntax in other languages. For language-specific transaction syntax, see the Transactions section of the Apache TinkerPop documentation for [Java](https://tinkerpop.apache.org/docs/current/reference/#gremlin-java-transactions), [Python](https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-transactions), [Javascript](https://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript-transactions), [.NET](https://tinkerpop.apache.org/docs/current/reference/#gremlin-dotnet-transactions), and [Go](https://tinkerpop.apache.org/docs/current/reference/#gremlin-go-transactions). @@ -110,0 +117,25 @@ Sessionless read-only queries are executed under [SNAPSHOT](./transactions-isola +## Timeout behavior for bytecode commit and rollback + +When you use bytecode-based transactions with the `tx()` syntax, the `commit()` and `rollback()` operations are not subject to query timeout settings. Neither the global `neptune_query_timeout` parameter nor per-query timeout values set through `evaluationTimeout` apply to these operations. On the server, `commit()` and `rollback()` run without a time limit until they complete or encounter an error. + +On the client side, the Gremlin driver's `tx.commit()` and `tx.rollback()` calls will not complete until the server responds. Depending on the language, this might manifest as a blocking call or an unresolved async operation. No driver provides a built-in timeout setting that bounds these calls. Consult the API documentation for your specific Gremlin Language Variant for details on concurrency behavior around these transaction features. + +###### Important + +If a `commit()` or `rollback()` call takes longer than expected, it might be blocked by lock contention from a concurrent transaction. For more information about lock conflicts, see [Conflict Resolution Using Lock-Wait Timeouts](./transactions-neptune.html#transactions-neptune-conflicts). + +If you need to bound the time your application waits for a `commit()` or `rollback()`, you can use your language's concurrency features to apply a client-side timeout. If the client-side timeout fires, the server continues processing the operation. The server-side operation holds a worker thread until it completes. After a client-side timeout, close the connection and create a new one rather than reusing the existing connection, because the transaction state is indeterminate. + +### Server-side transaction cleanup + +If a client disconnects or abandons a transaction without committing or rolling back, Neptune has server-side mechanisms that eventually clean up the orphaned transaction: + + * **Session timeout** – Bytecode-based sessions that remain idle for longer than the maximum session lifetime (10 minutes) are closed, and any open transaction is rolled back. + + * **Connection idle timeout** – Neptune closes WebSocket connections that are idle for approximately 20 minutes. When the connection closes, the server rolls back any open transaction associated with that connection. + + + + +These cleanup mechanisms are safety nets. We recommend that you always explicitly commit or roll back transactions when you are finished with them. +