You are viewing a plain text version of this content. The canonical link for it is here.

Posted to commits@tinkerpop.apache.org by "kenhuuu (via GitHub)" <gi...@apache.org> on 2024/11/19 23:15:29 UTC

[PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

kenhuuu opened a new pull request, #2908:
URL: https://github.com/apache/tinkerpop/pull/2908

   Please look over this documentation change for either inaccurate information or missing information.
   
   VOTE +1
   
   <!--
   Thanks for contributing! Reminders:
   + TARGET the earliest branch where you want the change
       3.7-dev -> 3.7.4 (non-breaking)
       master  -> 4.0.0
   + Committers will MERGE the PR forward to newer versions
   + ADD entry to the CHANGELOG.asciidoc for the targeted version
       Do not reference a JIRA number there
   + ADD JIRA number to title and link in description
   + PRs requires 3 +1s from committers OR
                  1 +1 and 7 day wait to merge.
   + MORE details: https://s.apache.org/rtnal
   -->


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850368919


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1341,6 +1284,18 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#security[reference docum
 NOTE: While Gremlin Server supports this authorization feature it is not a feature that TinkerPop requires of graph
 providers as part of the agreement between client and server.
 
+=== IO Tests
+
+The IO test suite is a collection of files that contain the expected outcome of serialization of certain types. These
+tests can be used to determine if a particular serializer has been correctly implemented. In general, a driver should
+be able to "round trip" each of these types. That is, it should be able to both read from and write to those exact same
+bytes. There may be some limitations based the types available in your driver's language, so it is not always possible

Review Comment:
   > There may be some limitations based the types available in your driver's language
   
   "based on the types"?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1870397565


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -2988,8 +2980,6 @@ The following `ResponseMessage` is a typical example of the typical successful r
 }
 ----
 
-=== Extended
-
 Note that the "extended" types require the addition of the separate `GraphSONXModuleV4d0` module as follows:

Review Comment:
   It probably doesn't need to exist, but I would use the milestone 1 release to make sure that is the case before updating it.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850330534


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No
+|g |The name of the graph traversal source to which the query applies. Default: "g" |String containing traversal source name |No
+|language |The name of the ScriptEngine to use to parse the gremlin query. Default: "gremlin-lang" |String containing ScriptEngine name |No
+|materializeProperties |Whether to include all properties for results. One of "tokens" or "all". |String |No
+|bulked |Whether the result should be "bulked" (only applies to GraphBinary) |Boolean |No
+|=========================================================
+
+=== HTTP Response Format
+
+[source,text]
+----
+HTTP/1.1 200
+Content-type: <mimetype>
+Transfer-Encoding: chunked
+Gremlin-RequestId: <uuid>
+{
+  "result": list,
+  "status": object
+}
+----
+
+NOTE: While this response message is expected for all serialized responses, there may be some errors that are not
+serialized. In that case, the `Content-Type` of the response should be `application/json` and the JSON should contain a
+`message` key.
+
+==== Response Message Format
+
+[width="100%",cols="3,10a",options="header"]
+|=========================================================
+|Key |Description
+|result |A map that contains the result data.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!data !A list of result objects. !Array !Yes
+!=========================================================
+|status |A map that contains the status of the result.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!code !The actual status code of the result. !Number !Yes

Review Comment:
   link to the error codes?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.

Cole-Greer commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850765117


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -19,9 +19,11 @@ limitations under the License.
 
 image:gremlin-graphson.png[width=350,float=left] GraphSON is a JSON-based format that is designed for human readable
 output that is easily supported in any programming language through the wide-array of JSON parsing libraries that
-exist on virtually all platforms. GraphSON is considered both a "graph" format and a generalized object serialization
-format. That characteristic makes it useful as a serialization format for Gremlin Server where arbitrary objects
-of varying types may be returned as results.
+exist on virtually all platforms. GraphSON versions 1 to 3 were considered to be both a "graph" format and a
+generalized object serialization format. That characteristic makes it useful as a serialization format for Gremlin
+Server where arbitrary objects of varying types may be returned as results. However, starting in GraphSON 4, GraphSON
+is only intended to be a network serialization format that is only able to serialize specific types defined by the
+format. It is only meant to be used between language variants and the Gremlin Server.

Review Comment:
   Is it fair to say that GraphSON 4 is a useful "graph format" for any graph which is limited to containing TinkerPop serializable types?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864052944


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API

Review Comment:
   I had it this way because I thought that the HTTP API was something both driver providers and graph providers should know, but I guess only driver providers need to directly implement it. I've pushed this whole section back into the graph driver providers section



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850350518


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.
+|language |The script's language.  The default is `gremlin-lang`.
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds.  The default value is server dependent.
+|materializeProperties |Determines if properties will be included in `Element` results.
+|bindings |A `Map` of arbitrary parameters to pass to the server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|g |The name of the `GraphTraversalSource` to use on the server.  The default is `g`.
 |=========================================================
 
-This message can be serialized in any fashion that is supported by Gremlin Server.  New serialization methods can
-be plugged in by implementing a `ServiceLoader` enabled `MessageSerializer`, however Gremlin Server provides for
+This message can be serialized in any fashion that is supported by Gremlin Server.  Gremlin Server provides for
 JSON serialization by default which will be good enough for purposes of most developers building drivers.
 A `RequestMessage` to evaluate a script with variable bindings looks like this in JSON:
 
 [source,js]
 ----
-{ "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
-  "op":"eval",
-  "processor":"",
-  "args":{"gremlin":"g.V(x).out()",
-          "bindings":{"x":1},
-          "language":"gremlin-groovy"}}
+{ "gremlin":"g.V(x).out()",
+  "bindings":{"x":1},
+  "language":"gremlin-groovy"}}
 ----
 
 The above JSON represents the "body" of the request to send to Gremlin Server. When sending this "body" over

Review Comment:
   more on the point of JSON - you called it a pseudo-JSON earlier in your writing. perhaps it is a "pseudo-request" around which you write this section of doc?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850343204


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.

Review Comment:
   is this table a duplicate of what was in the HTTP section? any reason to have it in both places? shouldn't this just link to the HTTP section of the table? also, note this version of the table still references the "op" code.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850425219


##########
docs/src/upgrade/release-4.x.x.asciidoc:
##########
@@ -357,4 +402,35 @@ for the implementations. Gremlin Server formerly supported the two-arg `Authenti
 instantiating new custom instances. It now expects implementations of `AbstractAuthenticationHandler` to use a
 three-arg constructor that takes `Authenticator`, `Authorizer`, and `Settings`.
 
+===== GraphManager Changes
+
+The `beforeQueryStart()`, `onQueryError()`, and `onQuerySuccess()` of `GraphManager` have been removed. These were
+originally intended to give providers more insight into when execution occurs in the server and the outcome of that
+execution. However, they depended on `RequestMessage` containing a Request ID, which isn't the case anymore.
+
+===== Gremlin Server Updates
+
+The `OpProcessor` extension point of the server has been removed. In order to extend the functionality of the Gremlin
+Server, you have to implement your own `Channelizer`.
+
+If you are a provider that makes use of the Gremlin Server, you may need to update server configuration YAML files that
+you provide to your users. With the change from WebSockets to HTTP, some of the previous default values are invalid and
+some of the fields no longer exist. See link:https://tinkerpop.apache.org/docs/4.0.0/reference/#_configuring_2[options]
+for an updated list. One of the most important changes is to the `Channelizer` configuration as only the
+`HttpChannelizer` remains and the rest have been removed.
+
 ==== Graph Driver Providers
+
+===== Application Layer Protocol Support
+
+HTTP/1.1 is now the only supported application-layer protocol and WebSockets support is dropped. Please follow the
+instructions in the
+link:https://tinkerpop.apache.org/docs/4.0.0/dev/provider/#_graph_driver_provider_requirements[provider documentation]
+for more detailed information. The subprotocol remains fairly similar but has been adjusted to work better with HTTP.
+Also, the move to HTTP means that SASL has been removed as an authentication mechanism and only HTTP basic remains.
+
+===== Request Interceptor

Review Comment:
   as mentioned elsewhere "recommended" is fine, but it might be help to be more explicit as to "why" by mentioning that not allowing for interceptor capabilities may preclude the driver from working with certain providers.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#issuecomment-2518749005

   Addressed comments and merging due to lazy consensus.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864055301


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -2988,8 +2980,6 @@ The following `ResponseMessage` is a typical example of the typical successful r
 }
 ----
 
-=== Extended
-
 Note that the "extended" types require the addition of the separate `GraphSONXModuleV4d0` module as follows:

Review Comment:
   I decided to leave it as is. GraphSONXModule still exists so it might still be proper to call them "extended" even though those sections in the document have been removed. What do you think?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850328961


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No
+|g |The name of the graph traversal source to which the query applies. Default: "g" |String containing traversal source name |No
+|language |The name of the ScriptEngine to use to parse the gremlin query. Default: "gremlin-lang" |String containing ScriptEngine name |No
+|materializeProperties |Whether to include all properties for results. One of "tokens" or "all". |String |No
+|bulked |Whether the result should be "bulked" (only applies to GraphBinary) |Boolean |No
+|=========================================================
+
+=== HTTP Response Format
+
+[source,text]
+----
+HTTP/1.1 200
+Content-type: <mimetype>
+Transfer-Encoding: chunked
+Gremlin-RequestId: <uuid>
+{
+  "result": list,
+  "status": object
+}
+----
+
+NOTE: While this response message is expected for all serialized responses, there may be some errors that are not
+serialized. In that case, the `Content-Type` of the response should be `application/json` and the JSON should contain a
+`message` key.
+
+==== Response Message Format
+
+[width="100%",cols="3,10a",options="header"]
+|=========================================================
+|Key |Description
+|result |A map that contains the result data.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!data !A list of result objects. !Array !Yes
+!=========================================================
+|status |A map that contains the status of the result.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!code !The actual status code of the result. !Number !Yes
+!exception !A class of exception if an error occurred. !String !No
+!message !The error message if an error occurred. !String !No
+!=========================================================
+|=========================================================
+
+==== Expected Response HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Content-Type |The MIME type of the serialized body which is based on the request's `Accept` header. May also be "application/json". |Yes |N/A
+|Gremlin-RequestId |The server generated UUID that is used as a request ID. |Yes |N/A
+|Transfer-Encoding |The server should attempt to chunk all responses. |No |"chunked"
+|=========================================================
+
+==== Response Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|         | application/json - some error cases may return JSON back
+|uuid |A randomly generated UUID string.
+|=========================================================
+
+==== Trailing Headers
+
+Error responses will have trailing headers in addition to the status object in the response body. This information is
+duplicated and should be the same, so graph driver providers should use whichever is easier for them. The trailers, however, will only contain the `Status` and `Exception` without the `Message`.
+
+=== HTTP Examples
+
+For examples of actual requests and responses, take a look at the IO documentation for
+link:https://tinkerpop.apache.org/docs/3.7.3/dev/io/#_requestmessage[GraphSON requests] and

Review Comment:
   should these links be hardcoded to 3.7.3? prefer `/current`?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850332546


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -971,19 +1133,16 @@ extensible nature of Gremlin Server, it is difficult to provide an authoritative
 It is however possible to describe the core communication protocol using the standard out-of-the-box configuration
 which should provide enough information to develop a driver for a specific language.
 
-image::gremlin-server-flow.png[width=300,float=right]
-
 Gremlin Server is distributed with a configuration that utilizes link:http://en.wikipedia.org/wiki/WebSocket[WebSocket]
 with a custom sub-protocol.  Under this configuration, Gremlin Server accepts requests containing a Gremlin script,
 evaluates that script and then streams back the results.  The notion of "streaming" is depicted in the diagram to the

Review Comment:
   it appears your deleted the diagram, but the text still refers to it. 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864054023


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.
+|language |The script's language.  The default is `gremlin-lang`.
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds.  The default value is server dependent.
+|materializeProperties |Determines if properties will be included in `Element` results.
+|bindings |A `Map` of arbitrary parameters to pass to the server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|g |The name of the `GraphTraversalSource` to use on the server.  The default is `g`.
 |=========================================================
 
-This message can be serialized in any fashion that is supported by Gremlin Server.  New serialization methods can
-be plugged in by implementing a `ServiceLoader` enabled `MessageSerializer`, however Gremlin Server provides for
+This message can be serialized in any fashion that is supported by Gremlin Server.  Gremlin Server provides for
 JSON serialization by default which will be good enough for purposes of most developers building drivers.
 A `RequestMessage` to evaluate a script with variable bindings looks like this in JSON:
 
 [source,js]
 ----
-{ "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
-  "op":"eval",
-  "processor":"",
-  "args":{"gremlin":"g.V(x).out()",
-          "bindings":{"x":1},
-          "language":"gremlin-groovy"}}
+{ "gremlin":"g.V(x).out()",
+  "bindings":{"x":1},
+  "language":"gremlin-groovy"}}
 ----
 
 The above JSON represents the "body" of the request to send to Gremlin Server. When sending this "body" over
-WebSocket, Gremlin Server can accept a packet frame using a "text" (1) or a "binary" (2) opcode. Using "text"
-is a bit more limited in that Gremlin Server will always process the body of that request as JSON.  Generally speaking
-"text" is just for testing purposes.
-
-The preferred method for sending requests to Gremlin Server is to use the "binary" opcode.  In this case, a "header"
-will need be sent in addition to to the "body".  The "header" basically consists of a "mime type" so that Gremlin
-Server knows how to deserialize the `RequestMessage`. So, the actual byte array sent to Gremlin Server would be
-formatted as follows:
+HTTP, Gremlin Server expects that the "Content-Type" header will contain the MIME type name of the serializer.
+`application/json` should be used for plain JSON requests, such as the one used in the above example.
 
 image::gremlin-server-request.png[]
 
-The first byte represents the length of the "mime type" string value that follows.  Given the default configuration of
-Gremlin Server, this value should be set to `application/json`.  The "payload" represents the JSON message above
-encoded as bytes.
-
-NOTE: Gremlin Server will only accept masked packets as it pertains to a WebSocket packet header construction.
-
-When Gremlin Server receives that request, it will decode it given the "mime type", pass it to the requested
-`OpProcessor` which will execute the `op` defined in the message.  In this case, it will evaluate the script
-`g.V(x).out()` using the `bindings` supplied in the `args` and stream back the results in a series of
-`ResponseMessages`.  A `ResponseMessage` looks like this:
+When Gremlin Server receives that request, it will decode it given the "mime type", and execute it using the
+`ScriptEngine` specified by the `language` field.  In this case, it will evaluate the script `g.V(x).out()` using the
+`bindings` supplied in the `args` and stream back the results in HTTP chunks. When the chunks are combined, they will
+form a single `ResponseMessage`.  A `ResponseMessage` looks like this:
 
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |The identifier of the `RequestMessage` that generated this `ResponseMessage`.
-|status | The `status` contains a `Map` of three keys: `code` which refers to a `ResultCode` that is somewhat analogous to an link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP status code], `attributes` that represent a `Map` of protocol-level information, and `message` which is just a human-readable `String` usually associated with errors.
-|result | The `result` contains a `Map` of two keys: `data` which refers to the actual data returned from the server (the type of data is determined by the operation requested) and `meta` which is a `Map` of meta-data related to the response.
+|status | The `status` contains a `Map` of three keys: `code` which refers to the link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP status code], `exception` that is a `String` that describe the class of exception that the error falls ino, and `message` which is just a human-readable `String` usually associated with errors. For successul responses, only `status` is mandatory. 

Review Comment:
   Originally, I had it separated because one was supposed to represent the abstract concept of a `RequestMessage`/`ResponseMessage` and one was supposed to be the concrete HTTP framing around it. I agree, its probably duplicated so I've merged the two sections into one.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864054751


##########
docs/src/upgrade/release-4.x.x.asciidoc:
##########
@@ -292,6 +293,39 @@ PDT. Primitive PDTs are string-based representations of a primitive type support
 contain a map of fields. You should consult your provider's documentation to determine what types of fields a
 particular PDT may contain.
 
+==== Changes to Authentication and Authorization
+
+With the move to HTTP, the only authentication option supported out-of-the-box is HTTP basic access authentication
+(username/password). The SASL-based authentication mechanisms are no longer supported (e.g. Kerberos). Your graph
+system provider may choose to implement other authentication mechanisms over HTTP which you would have to use via a
+request interceptor. Refer to your provider's documentation to determine if other authentication mechanisms are
+available.
+
+==== Transactions Disabled

Review Comment:
   I changed the version at the top from 4.0.0 to 4.0.0.M1 and added a disclaimer in that section. The disclaimer says that there was an attempt to tag parts that might change with an IMPORTANT box.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850325759


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No
+|g |The name of the graph traversal source to which the query applies. Default: "g" |String containing traversal source name |No
+|language |The name of the ScriptEngine to use to parse the gremlin query. Default: "gremlin-lang" |String containing ScriptEngine name |No
+|materializeProperties |Whether to include all properties for results. One of "tokens" or "all". |String |No
+|bulked |Whether the result should be "bulked" (only applies to GraphBinary) |Boolean |No

Review Comment:
   could you clarify "bulked" a bit? or link to their meaning if described elsewhere?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850336687


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -971,19 +1133,16 @@ extensible nature of Gremlin Server, it is difficult to provide an authoritative
 It is however possible to describe the core communication protocol using the standard out-of-the-box configuration
 which should provide enough information to develop a driver for a specific language.
 
-image::gremlin-server-flow.png[width=300,float=right]
-
 Gremlin Server is distributed with a configuration that utilizes link:http://en.wikipedia.org/wiki/WebSocket[WebSocket]
 with a custom sub-protocol.  Under this configuration, Gremlin Server accepts requests containing a Gremlin script,
 evaluates that script and then streams back the results.  The notion of "streaming" is depicted in the diagram to the
 right.
 
-The diagram shows an incoming request to process the Gremlin script of `g.V()`.  Gremlin Server evaluates that script,
-getting an `Iterator` of vertices as a result, and steps through each `Vertex` within it.  The vertices are batched
-together given the `resultIterationBatchSize` configuration.  In this case, that value must be `2` given that each
-"response" contains two vertices.  Each response is serialized given the requested serializer type (JSON is likely
-best for non-JVM languages) and written back to the requesting client immediately.  Gremlin Server does not wait for
-the entire result to be iterated, before sending back a response.  It will send the responses as they are realized.
+Let's use the incoming request to process the Gremlin script of `g.V()` as an example.  Gremlin Server evaluates that 
+script, getting an `Iterator` of vertices as a result, and steps through each `Vertex` within it.  The vertices are
+batched together into an HTTP chunk.  Each response is serialized given the requested serializer type (GraphBinary is
+recommended) and written back to the requesting client immediately.  Gremlin Server does not wait for the entire result

Review Comment:
   the docs keep mentioning "GraphBinary is recommended" but do we say anywhere why this is the case? ultimately, GraphBinary will effectively be the only option for drivers, so perhaps the docs should just be more clear that this is just a M1 recommendation?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850419938


##########
docs/src/upgrade/release-4.x.x.asciidoc:
##########
@@ -292,6 +293,39 @@ PDT. Primitive PDTs are string-based representations of a primitive type support
 contain a map of fields. You should consult your provider's documentation to determine what types of fields a
 particular PDT may contain.
 
+==== Changes to Authentication and Authorization
+
+With the move to HTTP, the only authentication option supported out-of-the-box is HTTP basic access authentication
+(username/password). The SASL-based authentication mechanisms are no longer supported (e.g. Kerberos). Your graph
+system provider may choose to implement other authentication mechanisms over HTTP which you would have to use via a
+request interceptor. Refer to your provider's documentation to determine if other authentication mechanisms are
+available.
+
+==== Transactions Disabled

Review Comment:
   hmmm, this is true of M1, but not what will be 4.0 GA. Are these upgrade docs for the M1 or for 4.0 GA? i kinda feel like its the latter and that we need a different place to call out milestone limitations. how about adding:
   
   > == TinkerPop 4.0.0.M1
   > The 4.0.0.M1 is a milestone release. It is for meant as a preview version to try out the new HTTP API features in the the server and drivers. As this is a milestone version only, you can expect breaking changes to occur in future milestones for 4.0.0 on the way to its General Availability release.  The following sections detail important limitations and constraints pertinent to this milestone that may or may not apply to General Availability. 
   
   as a new section and anything that is specific to M1 goes in there with 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864052424


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -19,9 +19,11 @@ limitations under the License.
 
 image:gremlin-graphson.png[width=350,float=left] GraphSON is a JSON-based format that is designed for human readable
 output that is easily supported in any programming language through the wide-array of JSON parsing libraries that
-exist on virtually all platforms. GraphSON is considered both a "graph" format and a generalized object serialization
-format. That characteristic makes it useful as a serialization format for Gremlin Server where arbitrary objects
-of varying types may be returned as results.
+exist on virtually all platforms. GraphSON versions 1 to 3 were considered to be both a "graph" format and a
+generalized object serialization format. That characteristic makes it useful as a serialization format for Gremlin
+Server where arbitrary objects of varying types may be returned as results. However, starting in GraphSON 4, GraphSON
+is only intended to be a network serialization format that is only able to serialize specific types defined by the
+format. It is only meant to be used between language variants and the Gremlin Server.

Review Comment:
   > is it just language variants? that seems to rule out pure http based requests, no?
   updated to say that its intended to work with the HTTP API
   
   > Is it fair to say that GraphSON 4 is a useful "graph format" for any graph which is limited to containing TinkerPop serializable types?
   sure, but I don't think it would ever be used that way so I wouldn't phrase it that way
   



##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -19,9 +19,11 @@ limitations under the License.
 
 image:gremlin-graphson.png[width=350,float=left] GraphSON is a JSON-based format that is designed for human readable
 output that is easily supported in any programming language through the wide-array of JSON parsing libraries that
-exist on virtually all platforms. GraphSON is considered both a "graph" format and a generalized object serialization
-format. That characteristic makes it useful as a serialization format for Gremlin Server where arbitrary objects
-of varying types may be returned as results.
+exist on virtually all platforms. GraphSON versions 1 to 3 were considered to be both a "graph" format and a
+generalized object serialization format. That characteristic makes it useful as a serialization format for Gremlin
+Server where arbitrary objects of varying types may be returned as results. However, starting in GraphSON 4, GraphSON
+is only intended to be a network serialization format that is only able to serialize specific types defined by the
+format. It is only meant to be used between language variants and the Gremlin Server.

Review Comment:
   > is it just language variants? that seems to rule out pure http based requests, no?
   
   updated to say that its intended to work with the HTTP API
   
   > Is it fair to say that GraphSON 4 is a useful "graph format" for any graph which is limited to containing TinkerPop serializable types?
   
   sure, but I don't think it would ever be used that way so I wouldn't phrase it that way
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864054176


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1066,266 +1211,64 @@ In this case the `ResponseMessage` returned to the client would look something l
 {"result":{"data":[{"id": 2,"label": "person","type": "vertex","properties": [
   {"id": 2, "value": "vadas", "label": "name"},
   {"id": 3, "value": 27, "label": "age"}]},
-  ], "meta":{}},
- "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
- "status":{"code":206,"attributes":{},"message":""}}
+  ]},
+ "status":{"code":200}}
 ----
 
-Gremlin Server is capable of streaming results such that additional responses will arrive over the WebSocket connection until
-the iteration of the result on the server is complete.  Each successful incremental message will have a `ResultCode`
-of `206`. Termination of the stream will be marked by a final `200` status code.  Note that all messages without a
-`206` represent terminating conditions for a request.  The following table details the various status codes that
-Gremlin Server will send:
+Note that this is the expected response if the `content-type` is a GraphSON or GraphBinary MIME type. Another issue may
+have occurred that prevented the server from returning a serialized response, in which case the serializer will use the
+`content-type: application/json`. Be sure to parse the response based on the `content-type` header.
+
+Gremlin Server is capable of streaming results, with additional responses arriving over HTTP in chunks until the
+iteration of the result on the server is complete.  The following table details the HTTP status codes that Gremlin
+Server will send:
 
 [width="100%",cols="2,2,9",options="header"]
 |=========================================================
 |Code |Name |Description
 |200 |SUCCESS |The server successfully processed a request to completion - there are no messages remaining in this stream.
 |204 |NO CONTENT |The server processed the request but there is no result to return (e.g. an `Iterator` with no elements) - there are no messages remaining in this stream.
 |206 |PARTIAL CONTENT |The server successfully returned some content, but there is more in the stream to arrive - wait for a `SUCCESS` to signify the end of the stream.
+|400 |BAD REQUEST |There was a problem with the HTTP request.
 |401 |UNAUTHORIZED |The request attempted to access resources that the requesting user did not have access to.
 |403 |FORBIDDEN |The server could authenticate the request, but will not fulfill it.
-|407 |AUTHENTICATE |A challenge from the server for the client to authenticate its request.
-|497 |REQUEST ERROR SERIALIZATION |The request message contained an object that was not serializable.
-|498 |REQUEST ERROR MALFORMED REQUEST |The request message was not properly formatted which means it could not be parsed at all or the "op" code was not recognized such that Gremlin Server could properly route it for processing.  Check the message format and retry the request.
-|499 |REQUEST ERROR INVALID REQUEST ARGUMENTS |The request message was parseable, but the arguments supplied in the message were in conflict or incomplete. Check the message format and retry the request.
-|500 |SERVER ERROR |A general server error occurred that prevented the request from being processed.
-|595 |SERVER ERROR FAIL STEP | A server error that is produced when the `fail()` step is triggered. The returned exception will include information consistent with the `Failure` interface.
-|596 |SERVER ERROR TEMPORARY |A server error occurred, but it was temporary in nature and therefore the client is free to retry it's request as-is with the potential for success.
-|597 |SERVER ERROR EVALUATION |The script submitted for processing evaluated in the `ScriptEngine` with errors and could not be processed.  Check the script submitted for syntax errors or other problems and then resubmit.
-|598 |SERVER ERROR TIMEOUT |The server exceeded one of the timeout settings for the request and could therefore only partially responded or did not respond at all.
-|599 |SERVER ERROR SERIALIZATION |The server was not capable of serializing an object that was returned from the script supplied on the request. Either transform the object into something Gremlin Server can process within the script or install mapper serialization classes to Gremlin Server.
+|404 |NOT FOUND |The server was unable to find the requested resource.
+|405 |METHOD NOT ALLOWED |The request used an unsupported method. The server only supports POST.
+|413 |REQUEST ENTITY TOO LARGE |The request was too large or the query could not be compiled due to size limitations.
+|500 |INTERNAL SERVER ERROR |A general server error occurred that prevented the request from being processed.
+|505 |HTTP VERSION NOT SUPPORTED |A server indicating that an unsupported version of HTTP is being used. Only HTTP/1.1 is supported.
 |=========================================================
 
 NOTE: Please refer to the link:https://tinkerpop.apache.org/docs/x.y.z/dev/io[IO Reference Documentation] for more
 examples of `RequestMessage` and `ResponseMessage` instances.
 
-NOTE: Tinkerpop provides a test server which may be useful for testing drivers. Details can be found
+NOTE: TinkerPop provides a test server which may be useful for testing drivers. Details can be found
 link:https://tinkerpop.apache.org/docs/current/dev/developer/#gremlin-socket-server-tests[here]
 
-=== OpProcessors Arguments
-
-The following sections define a non-exhaustive list of available operations and arguments for embedded `OpProcessors`
-(i.e. ones packaged with Gremlin Server).
-
-==== Common
+=== HTTP Request Interceptor
 
-All `OpProcessor` instances support these arguments.
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|batchSize |Int |When the result is an iterator this value defines the number of iterations each `ResponseMessage` should contain - overrides the `resultIterationBatchSize` server setting.
-|=========================================================
-
-==== Standard OpProcessor
-
-The "standard" `OpProcessor` handles requests for the primary function of Gremlin Server - executing Gremlin.
-Requests made to this `OpProcessor` are "sessionless" in the sense that a request must encapsulate the entirety
-of a transaction.  There is no state maintained between requests.  A transaction is started when the script is first
-evaluated and is committed when the script completes (or rolled back if an error occurred).
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |As this is the default `OpProcessor` this value can be set to an empty string.
-|op |[width="100%",cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`eval` !Evaluate a Gremlin script provided as a `String`.
-!=========================================================
-|=========================================================
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|saslMechanism |String | The SASL mechanism: `PLAIN` or `GSSAPI`. Note that it is up to the server implementation to use or disregard this setting (default implementation in Gremlin Server ignores it).
-|=========================================================
-
-**`eval` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The Gremlin script to evaluate.
-|bindings |Map |A map of key/value pairs to apply as variables in the context of the Gremlin script.
-|language |String |The flavor of Gremlin used (e.g. `gremlin-groovy`).
-|aliases |Map |A map of key/value pairs that allow globally bound `Graph` and `TraversalSource` objects to
-be aliased to different variable names for purposes of the current request.  The value represents the name of the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1` and `g2`, it would be possible
-to send an alias pair with key of "g" and value of "g2" and thus allow the script to refer to "g2" simply as "g".
-|evaluationTimeout |Long |An override for the server setting that determines the maximum time to wait for a script to execute on the server.
-|=========================================================
-
-==== Session OpProcessor
-
-The "session" `OpProcessor` handles requests for the primary function of Gremlin Server - executing Gremlin. It is
-like the "standard" `OpProcessor`, but instead maintains state between sessions and allows the option to leave all
-transaction management up to the calling client.  It is important that clients that open sessions, commit or roll
-them back, however Gremlin Server will try to clean up such things when a session is killed that has been abandoned.
-It is important to consider that a session can only be maintained with a single machine.  In the event that multiple
-Gremlin Server are deployed, session state is not shared among them.
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |This value should be set to `session`
-|op |
-[cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`eval` !Evaluate a Gremlin script provided as a `String`.
-!`close` !Deprecated. Gremlin-Server will only return a `NO CONTENT` message.
-|=========================================================
-
-NOTE: The "close" message related to sessions was deprecated as of 3.3.11. Closing sessions now relies on closing the connections. The function to accept `close` message on the server was removed
-in 3.5.0, but has been added back as of 3.5.2. Servers wishing to be compatible with older versions of the driver need only send back a `NO_CONTENT` for
-this message (which is what Gremlin Server does as of 3.5.0). Drivers wishing to be compatible with servers prior to
-3.3.11 may continue to send the message on calls to `close()`, otherwise such code can be removed.
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|saslMechanism |String | The SASL mechanism: `PLAIN` or `GSSAPI`. Note that it is up to the server implementation to use or disregard this setting (default implementation in Gremlin Server ignores it).
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|=========================================================
-
-**`eval` operation arguments**
-
-[width="100%",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The Gremlin script to evaluate.
-|session |String | *Required* The session identifier for the current session - typically this value should be a UUID (the session will be created if it doesn't exist).
-|manageTransaction |Boolean |When set to `true` the transaction for the current request is auto-committed or rolled-back as are done with sessionless requests - defaulted to `false`.
-|bindings |Map |A map of key/value pairs to apply as variables in the context of the Gremlin script.
-|evaluationTimeout |Long |An override for the server setting that determines the maximum time to wait for a script to execute on the server.
-|language |String |The flavor of Gremlin used (e.g. `gremlin-groovy`)
-|aliases |Map |A map of key/value pairs that allow globally bound `Graph` and `TraversalSource` objects to
-be aliased to different variable names for purposes of the current request.  The value represents the name the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1` and `g2`, it would be possible
-to send an alias pair with key of "g" and value of "g2" and thus allow the script to refer to "g2" simply as "g".
-|=========================================================
-
-**`close` operation arguments**
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|session |String | *Required* The session identifier for the session to close.
-|force |Boolean | Determines if the session should be force closed when the client is closed. Force closing will not
-attempt to close open transactions from existing running jobs and leave it to the underlying graph to decided how to
-proceed with those orphaned transactions. Setting this to `true` tends to lead to faster close operation and release
-of resources which can be desirable if Gremlin Server has a long session timeout and a long script evaluation timeout
-as attempts to close long run jobs can occur more rapidly. If not provided, this value is `false`.
-|=========================================================
-
-==== Traversal OpProcessor
-
-Both the Standard and Session OpProcessors allow for Gremlin scripts to be submitted to the server. The
-`TraversalOpProcessor` however allows Gremlin `Bytecode` to be submitted to the server. Supporting this `OpProcessor`
-makes it possible for a link:https://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-drivers-variants[Gremlin Language Variant]
-to submit a `Traversal` directly to Gremlin Server in the native language of the GLV without having to use a script in
-a different language.
-
-Unlike Standard and Session OpProcessors, the Traversal OpProcessor does not simply return the results of the
-`Traversal`. It instead returns `Traverser` objects which allows the client to take advantage of
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#barrier-step[bulking]. To describe this interaction more
-directly, the returned `Traverser` will represent some value from the `Traversal` result and the number of times it
-is represented in the full stream of results. So, if a `Traversal` happens to return the same vertex twenty times
-it won't return twenty instances of the same object. It will return one in `Traverser` with the `bulk` value set to
-twenty. Under this model, the amount of processing and network overhead can be reduced considerably.
-
-To demonstrate consider this example:
-
-[gremlin-groovy]
-----
-cluster = Cluster.open()
-client = cluster.connect()
-aliased = client.alias("g")
-g = traversal().with(org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph.instance())     <1>
-rs = aliased.submit(g.V().both().barrier().both().barrier()).all().get()                    <2>
-aliased.submit(g.V().both().barrier().both().barrier().count()).all().get().get(0).getInt() <3>
-rs.collect{[value: it.getObject().get(), bulk: it.getObject().bulk()]}                      <4>
-----
-
-<1> All commands through this step are just designed to demonstrate bulking with Gremlin Server and don't represent
-a real-world way that this feature would be used.
-<2> Submit a `Traversal` that happens to ensure that the server uses bulking. Note that a `Traverser` is returned
-and that there are only six results.
-<3> In actuality, however, if this same `Traversal` is iterated there are thirty results. Without bulking, the previous
-request would have sent back thirty traversers.
-<4> Note that the sum of the bulk of each `Traverser` is thirty.
-
-The full iteration of a `Traversal` is thus left to the client. It must interpret the bulk on the `Traverser` and
-unroll it to represent the actual number of times it exists when iterated. The unrolling is typically handled
-directly within TinkerPop's remote traversal implementations.
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |This value should be set to `traversal`
-|op |
-[cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`bytecode` !A request that contains the `Bytecode` representation of a `Traversal`.
-|=========================================================
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|=========================================================
-
-**`bytecode` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The `Bytecode` representation of a `Traversal`.
-|aliases |Map | *Required* A map with a single key/value pair that refers to a globally bound `TraversalSource` object
-to be aliased to different variable names for purposes of the current request.  The value represents the name of the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1`, it would be possible
-to send an alias pair with key of "g" and value of "g1" and thus allow the script to refer to "g1" simply as "g". Note
-that unlike users of `alias` in other contexts, in this case, the key can *only* be set to "g" and there can be only
-one key value pair present (since only one `Traversal` is being submitted, there is no sense to having more than a
-single alias).
-|=========================================================
+All graph drivers are expected to support HTTP request intercepting.  This means that the user of the graph driver

Review Comment:
   rephrased this section to be like (1)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1870178115


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -2988,8 +2980,6 @@ The following `ResponseMessage` is a typical example of the typical successful r
 }
 ----
 
-=== Extended
-
 Note that the "extended" types require the addition of the separate `GraphSONXModuleV4d0` module as follows:

Review Comment:
   why does "GraphSONXModule" need to exist?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850355671


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.
+|language |The script's language.  The default is `gremlin-lang`.
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds.  The default value is server dependent.
+|materializeProperties |Determines if properties will be included in `Element` results.
+|bindings |A `Map` of arbitrary parameters to pass to the server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|g |The name of the `GraphTraversalSource` to use on the server.  The default is `g`.
 |=========================================================
 
-This message can be serialized in any fashion that is supported by Gremlin Server.  New serialization methods can
-be plugged in by implementing a `ServiceLoader` enabled `MessageSerializer`, however Gremlin Server provides for
+This message can be serialized in any fashion that is supported by Gremlin Server.  Gremlin Server provides for
 JSON serialization by default which will be good enough for purposes of most developers building drivers.
 A `RequestMessage` to evaluate a script with variable bindings looks like this in JSON:
 
 [source,js]
 ----
-{ "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
-  "op":"eval",
-  "processor":"",
-  "args":{"gremlin":"g.V(x).out()",
-          "bindings":{"x":1},
-          "language":"gremlin-groovy"}}
+{ "gremlin":"g.V(x).out()",
+  "bindings":{"x":1},
+  "language":"gremlin-groovy"}}
 ----
 
 The above JSON represents the "body" of the request to send to Gremlin Server. When sending this "body" over
-WebSocket, Gremlin Server can accept a packet frame using a "text" (1) or a "binary" (2) opcode. Using "text"
-is a bit more limited in that Gremlin Server will always process the body of that request as JSON.  Generally speaking
-"text" is just for testing purposes.
-
-The preferred method for sending requests to Gremlin Server is to use the "binary" opcode.  In this case, a "header"
-will need be sent in addition to to the "body".  The "header" basically consists of a "mime type" so that Gremlin
-Server knows how to deserialize the `RequestMessage`. So, the actual byte array sent to Gremlin Server would be
-formatted as follows:
+HTTP, Gremlin Server expects that the "Content-Type" header will contain the MIME type name of the serializer.
+`application/json` should be used for plain JSON requests, such as the one used in the above example.
 
 image::gremlin-server-request.png[]
 
-The first byte represents the length of the "mime type" string value that follows.  Given the default configuration of
-Gremlin Server, this value should be set to `application/json`.  The "payload" represents the JSON message above
-encoded as bytes.
-
-NOTE: Gremlin Server will only accept masked packets as it pertains to a WebSocket packet header construction.
-
-When Gremlin Server receives that request, it will decode it given the "mime type", pass it to the requested
-`OpProcessor` which will execute the `op` defined in the message.  In this case, it will evaluate the script
-`g.V(x).out()` using the `bindings` supplied in the `args` and stream back the results in a series of
-`ResponseMessages`.  A `ResponseMessage` looks like this:
+When Gremlin Server receives that request, it will decode it given the "mime type", and execute it using the
+`ScriptEngine` specified by the `language` field.  In this case, it will evaluate the script `g.V(x).out()` using the
+`bindings` supplied in the `args` and stream back the results in HTTP chunks. When the chunks are combined, they will
+form a single `ResponseMessage`.  A `ResponseMessage` looks like this:
 
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |The identifier of the `RequestMessage` that generated this `ResponseMessage`.
-|status | The `status` contains a `Map` of three keys: `code` which refers to a `ResultCode` that is somewhat analogous to an link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP status code], `attributes` that represent a `Map` of protocol-level information, and `message` which is just a human-readable `String` usually associated with errors.
-|result | The `result` contains a `Map` of two keys: `data` which refers to the actual data returned from the server (the type of data is determined by the operation requested) and `meta` which is a `Map` of meta-data related to the response.
+|status | The `status` contains a `Map` of three keys: `code` which refers to the link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP status code], `exception` that is a `String` that describe the class of exception that the error falls ino, and `message` which is just a human-readable `String` usually associated with errors. For successul responses, only `status` is mandatory. 

Review Comment:
   again - i'm not sure we should duplicate the table and should just refer to the HTTP section. you can add an anchor or something to link directly to the individual tables. moreover there are details there that the driver developer will want to know - stuff like the trailing headers details perhaps?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850328961


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No
+|g |The name of the graph traversal source to which the query applies. Default: "g" |String containing traversal source name |No
+|language |The name of the ScriptEngine to use to parse the gremlin query. Default: "gremlin-lang" |String containing ScriptEngine name |No
+|materializeProperties |Whether to include all properties for results. One of "tokens" or "all". |String |No
+|bulked |Whether the result should be "bulked" (only applies to GraphBinary) |Boolean |No
+|=========================================================
+
+=== HTTP Response Format
+
+[source,text]
+----
+HTTP/1.1 200
+Content-type: <mimetype>
+Transfer-Encoding: chunked
+Gremlin-RequestId: <uuid>
+{
+  "result": list,
+  "status": object
+}
+----
+
+NOTE: While this response message is expected for all serialized responses, there may be some errors that are not
+serialized. In that case, the `Content-Type` of the response should be `application/json` and the JSON should contain a
+`message` key.
+
+==== Response Message Format
+
+[width="100%",cols="3,10a",options="header"]
+|=========================================================
+|Key |Description
+|result |A map that contains the result data.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!data !A list of result objects. !Array !Yes
+!=========================================================
+|status |A map that contains the status of the result.
+[width="100%",cols="3,10,3,3",options="header"]
+!=========================================================
+!Name !Description !Required !Default
+!code !The actual status code of the result. !Number !Yes
+!exception !A class of exception if an error occurred. !String !No
+!message !The error message if an error occurred. !String !No
+!=========================================================
+|=========================================================
+
+==== Expected Response HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Content-Type |The MIME type of the serialized body which is based on the request's `Accept` header. May also be "application/json". |Yes |N/A
+|Gremlin-RequestId |The server generated UUID that is used as a request ID. |Yes |N/A
+|Transfer-Encoding |The server should attempt to chunk all responses. |No |"chunked"
+|=========================================================
+
+==== Response Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|         | application/json - some error cases may return JSON back
+|uuid |A randomly generated UUID string.
+|=========================================================
+
+==== Trailing Headers
+
+Error responses will have trailing headers in addition to the status object in the response body. This information is
+duplicated and should be the same, so graph driver providers should use whichever is easier for them. The trailers, however, will only contain the `Status` and `Exception` without the `Message`.
+
+=== HTTP Examples
+
+For examples of actual requests and responses, take a look at the IO documentation for
+link:https://tinkerpop.apache.org/docs/3.7.3/dev/io/#_requestmessage[GraphSON requests] and

Review Comment:
   should these links be hardcoded to 3.7.3? prefer `/x.y.z`?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850401942


##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -1024,6 +1022,26 @@ g2Client.submit("g.V()")
 The above code demonstrates how the `alias` method can be used such that the script need only contain a reference
 to "g" and "g1" and "g2" are automatically rebound into "g" on the server-side.
 
+==== RequestInterceptor

Review Comment:
   might be good to have a simple example here direct in the docs or link to one in:
   
   https://github.com/apache/tinkerpop/tree/master/gremlin-driver/src/main/java/examples 
   
   speaking of which, are those up to date?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850318623


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API

Review Comment:
   Something about the ordering of the Provider doc feels off to me. Someone implementing TinkerPop is the target reader. They likely would not start implementing by doing "HTTP API". The "Graph System Provider Requirements" are probably where most implementers would start their work. Could you give a bit of thought to organization and placement of this section?
   
   I'd suggest a paragraph at the end of the "Provider Documentation" section above that says something like:
   
   > Deciding which of the interfaces, protocols, and tests to implement depends largely on where your work fits in the TinkerPop system and how advanced you intend for that implementation to be. The following bullet points detail common provider projects that implementers undertake and what parts of the documentation will be most relevant to them in getting started:
   > 
   > * Building a TinkerPop compliant graph database 
   > * Building a Gremlin Server implementation to provide remote connectivity over HTTP and with Gremlin drivers
   > * Building a driver to work with Gremlin Server implementations
   > * Building a Gremlin execution engine
   
   The bullets are just possible sections that could likely replace the bullets above that just list the types of providers. Each could have some sort of introductory paragraph that gives an overview of what's involved in those tasks, links to docs we have and other hints to get started. I think that would introduce the sections below much better.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864053709


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.
+|language |The script's language.  The default is `gremlin-lang`.
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds.  The default value is server dependent.
+|materializeProperties |Determines if properties will be included in `Element` results.
+|bindings |A `Map` of arbitrary parameters to pass to the server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|g |The name of the `GraphTraversalSource` to use on the server.  The default is `g`.
 |=========================================================
 
-This message can be serialized in any fashion that is supported by Gremlin Server.  New serialization methods can
-be plugged in by implementing a `ServiceLoader` enabled `MessageSerializer`, however Gremlin Server provides for
+This message can be serialized in any fashion that is supported by Gremlin Server.  Gremlin Server provides for
 JSON serialization by default which will be good enough for purposes of most developers building drivers.
 A `RequestMessage` to evaluate a script with variable bindings looks like this in JSON:
 
 [source,js]
 ----
-{ "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
-  "op":"eval",
-  "processor":"",
-  "args":{"gremlin":"g.V(x).out()",
-          "bindings":{"x":1},
-          "language":"gremlin-groovy"}}
+{ "gremlin":"g.V(x).out()",
+  "bindings":{"x":1},
+  "language":"gremlin-groovy"}}
 ----
 
 The above JSON represents the "body" of the request to send to Gremlin Server. When sending this "body" over

Review Comment:
   this section has been removed.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850347072


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1007,56 +1167,41 @@ dependent on the operation being performed.  A `RequestMessage` has these fields
 [width="100%",cols="3,10",options="header"]
 |=========================================================
 |Key |Description
-|requestId |A link:http://en.wikipedia.org/wiki/Globally_unique_identifier[UUID] representing the unique identification for the request.
-|op |The name of the "operation" to execute based on the available `OpProcessor` configured in the Gremlin Server.  To evaluate a script, use `eval`.
-|processor |The name of the `OpProcessor` to utilize. The default `OpProcessor` for evaluating scripts is unnamed and therefore script evaluation purposes, this value can be an empty string.
-|args |A `Map` of arbitrary parameters to pass to Gremlin Server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|gremlin |The script to be executed by the server.
+|language |The script's language.  The default is `gremlin-lang`.
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds.  The default value is server dependent.
+|materializeProperties |Determines if properties will be included in `Element` results.
+|bindings |A `Map` of arbitrary parameters to pass to the server.  The requirements for the contents of this `Map` are dependent on the `op` selected.
+|g |The name of the `GraphTraversalSource` to use on the server.  The default is `g`.
 |=========================================================
 
-This message can be serialized in any fashion that is supported by Gremlin Server.  New serialization methods can
-be plugged in by implementing a `ServiceLoader` enabled `MessageSerializer`, however Gremlin Server provides for
+This message can be serialized in any fashion that is supported by Gremlin Server.  Gremlin Server provides for
 JSON serialization by default which will be good enough for purposes of most developers building drivers.

Review Comment:
   > Gremlin Server provides for JSON serialization by default which will be good enough for purposes of most developers building drivers.
   
   again, not sure we should be recommending JSON serialization drivers going forward, particularly for building them (probably not even a good statement in the old docs - probably a holdover from the Gryo days).
   
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.

Cole-Greer commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850808812


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -2988,8 +2980,6 @@ The following `ResponseMessage` is a typical example of the typical successful r
 }
 ----
 
-=== Extended
-
 Note that the "extended" types require the addition of the separate `GraphSONXModuleV4d0` module as follows:

Review Comment:
   This note needs updating if we are discarding the Core and Extended types categories



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850368919


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1341,6 +1284,18 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#security[reference docum
 NOTE: While Gremlin Server supports this authorization feature it is not a feature that TinkerPop requires of graph
 providers as part of the agreement between client and server.
 
+=== IO Tests
+
+The IO test suite is a collection of files that contain the expected outcome of serialization of certain types. These
+tests can be used to determine if a particular serializer has been correctly implemented. In general, a driver should
+be able to "round trip" each of these types. That is, it should be able to both read from and write to those exact same
+bytes. There may be some limitations based the types available in your driver's language, so it is not always possible

Review Comment:
   > There may be some limitations based the types available in your driver's language
   
   "based on the types"?
   
   >  so it is not always possible to round trip every type.
   
   could you supply an example please to make it clear when that happens and what folks would do in such a case?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.

Cole-Greer commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850777050


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -102,13 +104,11 @@ mime type is made explicit on requests to avoid breaking changes or unexpected r
 
 Version 4.0 of GraphSON was first introduced on TinkerPop 4.0.0 and is represented by the
 `application/vnd.gremlin-v4.0+json` mime type. There also exists an untyped version:
-`application/vnd.gremlin-v3.0+json;types=false`. It is very similar to GraphSON 3.0, with just several key differences:
+`application/vnd.gremlin-v4.0+json;types=false`. It is very similar to GraphSON 3.0, with just several key differences:

Review Comment:
   ```suggestion
   `application/vnd.gremlin-v4.0+json;types=false`. It is very similar to GraphSON 4.0, with just several key differences:
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1870308728


##########
docs/src/upgrade/release-4.x.x.asciidoc:
##########
@@ -21,15 +21,45 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 
 *4.0.0*
 
-== TinkerPop 4.0.0
+== TinkerPop 4.0.0.M1
 
 *Release Date: NOT OFFICIALLY RELEASED YET*
 
 Please see the link:https://github.com/apache/tinkerpop/blob/4.0.0/CHANGELOG.asciidoc#release-4-0-0[changelog] for a
 complete list of all the modifications that are part of this release.
 
+NOTE: 4.0.0.M1 is a milestone release. It is for meant as a preview version to try out the new HTTP API features in
+the server and drivers. As this is a milestone version only, you can expect breaking changes to occur in future

Review Comment:
   "server and drivers" - may as well get specific here and mention python and java



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864053401


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -971,19 +1133,16 @@ extensible nature of Gremlin Server, it is difficult to provide an authoritative
 It is however possible to describe the core communication protocol using the standard out-of-the-box configuration
 which should provide enough information to develop a driver for a specific language.
 
-image::gremlin-server-flow.png[width=300,float=right]
-
 Gremlin Server is distributed with a configuration that utilizes link:http://en.wikipedia.org/wiki/WebSocket[WebSocket]
 with a custom sub-protocol.  Under this configuration, Gremlin Server accepts requests containing a Gremlin script,
 evaluates that script and then streams back the results.  The notion of "streaming" is depicted in the diagram to the
 right.
 
-The diagram shows an incoming request to process the Gremlin script of `g.V()`.  Gremlin Server evaluates that script,
-getting an `Iterator` of vertices as a result, and steps through each `Vertex` within it.  The vertices are batched
-together given the `resultIterationBatchSize` configuration.  In this case, that value must be `2` given that each
-"response" contains two vertices.  Each response is serialized given the requested serializer type (JSON is likely
-best for non-JVM languages) and written back to the requesting client immediately.  Gremlin Server does not wait for
-the entire result to be iterated, before sending back a response.  It will send the responses as they are realized.
+Let's use the incoming request to process the Gremlin script of `g.V()` as an example.  Gremlin Server evaluates that 
+script, getting an `Iterator` of vertices as a result, and steps through each `Vertex` within it.  The vertices are
+batched together into an HTTP chunk.  Each response is serialized given the requested serializer type (GraphBinary is
+recommended) and written back to the requesting client immediately.  Gremlin Server does not wait for the entire result

Review Comment:
   Added new "serializer" section to explain more in-depth why GraphBinary is recommended.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850324154


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No

Review Comment:
   could you clarify "bindings" a bit? or link to their meaning if described elsewhere?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850396258


##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -814,46 +815,43 @@ The following table describes the various configuration options for the Gremlin
 |connectionPool.trustStore |File location for a SSL Certificate Chain to use when SSL is enabled. If this value is not provided and SSL is enabled, the default `TrustManager` will be used. |_none_
 |connectionPool.trustStorePassword |The password of the `trustStore` if it is password-protected |_none_
 |connectionPool.validationRequest |A script that is used to test server connectivity. A good script to use is one that evaluates quickly and returns no data. The default simply returns an empty string, but if a graph is required by a particular provider, a good traversal might be `g.inject()`. |_''_
-|connectionPool.connectionSetupTimeoutMillis | Duration of time in milliseconds provided for connection setup to complete which includes WebSocket protocol handshake and SSL handshake. |15000
-|connectionPool.idleConnectionTimeout | Duration of time in milliseconds that the driver will allow a channel to not receive read or writes before it automatically closes. |180000
+|enableBulkedResult |Sets whether the result from server should attempt to get bulked. |false
+|enableUserAgentOnConnect |Enables sending a user agent to the server during connection requests. More details can be found in provider docs link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#_graph_driver_provider_requirements[here].|true
 |hosts |The list of hosts that the driver will connect to. |localhost
-|jaasEntry |Sets the `AuthProperties.Property.JAAS_ENTRY` properties for authentication to Gremlin Server. |_none_
 |nioPoolSize |Size of the pool for handling request/response operations. |available processors
 |password |The password to submit on requests that require authentication. |_none_
 |path |The URL path to the Gremlin Server. |_/gremlin_
 |port |The port of the Gremlin Server to connect to. The same port will be applied for all hosts. |8192
-|protocol |Sets the `AuthProperties.Property.PROTOCOL` properties for authentication to Gremlin Server. |_none_
 |serializer.className |The fully qualified class name of the `MessageSerializer` that will be used to deserialize responses from the server. Note that the serializer configured on the client should be supported by the server configuration. |_none_
 |serializer.config |A `Map` of configuration settings for the serializer. |_none_
 |username |The username to submit on requests that require authentication. |_none_
 |workerPoolSize |Size of the pool for handling background work. |available processors * 2
-|enableUserAgentOnConnect |Enables sending a user agent to the server during connection requests. More details can be found in provider docs link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#_graph_driver_provider_requirements[here].|true
 |=========================================================
 
 Please see the link:https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/driver/Cluster.Builder.html[Cluster.Builder javadoc] to get more information on these settings.
 
 [[gremlin-java-transactions]]
 === Transactions
 
-Transactions with Java are best described in <<transactions,The Traversal - Transactions>> section of this
-documentation as Java covers both embedded and remote use cases.
+Transactions with Java isn't currently supported.
 
 [[gremlin-java-serialization]]
 === Serialization
 
 Remote systems like Gremlin Server and Remote Gremlin Providers respond to requests made in a particular serialization
 format and respond by serializing results to some format to be interpreted by the client. For JVM-based languages,
-there are two options for serialization: GraphSON and GraphBinary. It is important that the client and server
-have the same serializers configured in the same way or else one or the other will experience serialization exceptions
-and fail to always communicate. Discrepancy in serializer registration between client and server can happen fairly
-easily as different graph systems may automatically include serializers on the server-side, thus leaving the client
-to be configured manually. As an example:
+there are two options for serialization: GraphSON and GraphBinary. Note, however, that starting in the full release of

Review Comment:
   maybe we should have a standard warning banner for stuff that only expected in a particular milestone, that way we can write what's intended and it will be easy to search for banners to remove them later?
   
   > IMPORTANT: 4.0 Milestone Release - There is temporary support for GraphSON in the Java driver which will help with testing, but it is expected that the drivers will only support GraphBinary when GA is released.
   
   something like that? 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850386297


##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -824,55 +820,28 @@ They are all still evaluated locally.
 [[connecting-via-http]]
 === Connecting via HTTP
 
-image:gremlin-rexster.png[width=225,float=left] While the default behavior for Gremlin Server is to provide a
-WebSocket-based connection, it can also be configured to support plain HTTP web service.
-The HTTP endpoint provides for a communication protocol familiar to most developers, with a wide support of
-programming languages, tools and libraries for accessing it.  As a result, HTTP provides a fast way to get started
-with Gremlin Server.   It also may represent an easier upgrade path from link:https://github.com/tinkerpop/rexster[Rexster]
-as the API for the endpoint is very similar to Rexster's link:https://github.com/tinkerpop/rexster/wiki/Gremlin-Extension[Gremlin Extension].
-
-IMPORTANT: TinkerPop provides and supports this HTTP endpoint as a convenience and for legacy reasons, but users should
-prefer the recommended approach of bytcode based requests as described in <<connecting-gremlin,Connecting Gremlin>>
-section.
+image:gremlin-rexster.png[width=225,float=left] The HTTP endpoint provides for a communication protocol familiar to
+most developers, with a wide support of programming languages, tools and libraries for accessing it.  As a result, HTTP
+provides a fast way to get started with Gremlin Server.
 
-Gremlin Server provides for a single HTTP endpoint - a Gremlin evaluator - which allows the submission of a Gremlin
-script as a request.  For each request, it returns a response containing the serialized results of that script.
-To enable this endpoint, Gremlin Server needs to be configured with the `HttpChannelizer`, which replaces the default.
-The `WsAndHttpChannelizer` may also be configured to enable both WebSockets and the REST endpoint in the configuration
-file:
-
-[source,yaml]
-channelizer: org.apache.tinkerpop.gremlin.server.channel.HttpChannelizer
+Gremlin Server implements the link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#_http_api[TinkerPop HTTP API].
+It provides a single endpoint which allows for the submission of a Gremlin script as a request.  For each request, it
+returns a response containing the serialized results of that script.
 
-[source,yaml]
-channelizer: org.apache.tinkerpop.gremlin.server.channel.WsAndHttpChannelizer
-
-The `HttpChannelizer` is already configured in the `gremlin-server-rest-modern.yaml` file that is packaged with the Gremlin
+The `HttpChannelizer` is already configured in the `gremlin-server-modern.yaml` file that is packaged with the Gremlin
 Server distribution.  To utilize it, start Gremlin Server as follows:
 
 [source,text]
-bin/gremlin-server.sh conf/gremlin-server-rest-modern.yaml
+bin/gremlin-server.sh conf/gremlin-server-modern.yaml
 
 Once the server has started, issue a request.  Here's an example with link:http://curl.haxx.se/[cURL]:
 
-[source,text]
-$ curl "http://localhost:8182?gremlin=100-1"
-
-which returns:
-
-[source,js]
-{
-  "result":{"data":99,"meta":{}},
-  "requestId":"0581cdba-b152-45c4-80fa-3d36a6eecf1c",
-  "status":{"code":200,"attributes":{},"message":""}
-}
-
-The above example showed a `GET` operation, but the preferred method for this endpoint is `POST`:
+`POST` is the only supported method for the endpoint:

Review Comment:
   according to the diff this reads as:
   
   > Once the server has started, issue a request. Here’s an example with [cURL](http://curl.haxx.se/):
   
   >
   > POST is the only supported method for the endpoint:
   
   need to clean something up there.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850253495


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -19,9 +19,11 @@ limitations under the License.
 
 image:gremlin-graphson.png[width=350,float=left] GraphSON is a JSON-based format that is designed for human readable
 output that is easily supported in any programming language through the wide-array of JSON parsing libraries that
-exist on virtually all platforms. GraphSON is considered both a "graph" format and a generalized object serialization
-format. That characteristic makes it useful as a serialization format for Gremlin Server where arbitrary objects
-of varying types may be returned as results.
+exist on virtually all platforms. GraphSON versions 1 to 3 were considered to be both a "graph" format and a
+generalized object serialization format. That characteristic makes it useful as a serialization format for Gremlin
+Server where arbitrary objects of varying types may be returned as results. However, starting in GraphSON 4, GraphSON
+is only intended to be a network serialization format that is only able to serialize specific types defined by the
+format. It is only meant to be used between language variants and the Gremlin Server.

Review Comment:
   > It is only meant to be used between language variants and the Gremlin Server.
   
   is it just language variants? that seems to rule out pure http based requests, no?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.

spmallette commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1850366092


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -1066,266 +1211,64 @@ In this case the `ResponseMessage` returned to the client would look something l
 {"result":{"data":[{"id": 2,"label": "person","type": "vertex","properties": [
   {"id": 2, "value": "vadas", "label": "name"},
   {"id": 3, "value": 27, "label": "age"}]},
-  ], "meta":{}},
- "requestId":"1d6d02bd-8e56-421d-9438-3bd6d0079ff1",
- "status":{"code":206,"attributes":{},"message":""}}
+  ]},
+ "status":{"code":200}}
 ----
 
-Gremlin Server is capable of streaming results such that additional responses will arrive over the WebSocket connection until
-the iteration of the result on the server is complete.  Each successful incremental message will have a `ResultCode`
-of `206`. Termination of the stream will be marked by a final `200` status code.  Note that all messages without a
-`206` represent terminating conditions for a request.  The following table details the various status codes that
-Gremlin Server will send:
+Note that this is the expected response if the `content-type` is a GraphSON or GraphBinary MIME type. Another issue may
+have occurred that prevented the server from returning a serialized response, in which case the serializer will use the
+`content-type: application/json`. Be sure to parse the response based on the `content-type` header.
+
+Gremlin Server is capable of streaming results, with additional responses arriving over HTTP in chunks until the
+iteration of the result on the server is complete.  The following table details the HTTP status codes that Gremlin
+Server will send:
 
 [width="100%",cols="2,2,9",options="header"]
 |=========================================================
 |Code |Name |Description
 |200 |SUCCESS |The server successfully processed a request to completion - there are no messages remaining in this stream.
 |204 |NO CONTENT |The server processed the request but there is no result to return (e.g. an `Iterator` with no elements) - there are no messages remaining in this stream.
 |206 |PARTIAL CONTENT |The server successfully returned some content, but there is more in the stream to arrive - wait for a `SUCCESS` to signify the end of the stream.
+|400 |BAD REQUEST |There was a problem with the HTTP request.
 |401 |UNAUTHORIZED |The request attempted to access resources that the requesting user did not have access to.
 |403 |FORBIDDEN |The server could authenticate the request, but will not fulfill it.
-|407 |AUTHENTICATE |A challenge from the server for the client to authenticate its request.
-|497 |REQUEST ERROR SERIALIZATION |The request message contained an object that was not serializable.
-|498 |REQUEST ERROR MALFORMED REQUEST |The request message was not properly formatted which means it could not be parsed at all or the "op" code was not recognized such that Gremlin Server could properly route it for processing.  Check the message format and retry the request.
-|499 |REQUEST ERROR INVALID REQUEST ARGUMENTS |The request message was parseable, but the arguments supplied in the message were in conflict or incomplete. Check the message format and retry the request.
-|500 |SERVER ERROR |A general server error occurred that prevented the request from being processed.
-|595 |SERVER ERROR FAIL STEP | A server error that is produced when the `fail()` step is triggered. The returned exception will include information consistent with the `Failure` interface.
-|596 |SERVER ERROR TEMPORARY |A server error occurred, but it was temporary in nature and therefore the client is free to retry it's request as-is with the potential for success.
-|597 |SERVER ERROR EVALUATION |The script submitted for processing evaluated in the `ScriptEngine` with errors and could not be processed.  Check the script submitted for syntax errors or other problems and then resubmit.
-|598 |SERVER ERROR TIMEOUT |The server exceeded one of the timeout settings for the request and could therefore only partially responded or did not respond at all.
-|599 |SERVER ERROR SERIALIZATION |The server was not capable of serializing an object that was returned from the script supplied on the request. Either transform the object into something Gremlin Server can process within the script or install mapper serialization classes to Gremlin Server.
+|404 |NOT FOUND |The server was unable to find the requested resource.
+|405 |METHOD NOT ALLOWED |The request used an unsupported method. The server only supports POST.
+|413 |REQUEST ENTITY TOO LARGE |The request was too large or the query could not be compiled due to size limitations.
+|500 |INTERNAL SERVER ERROR |A general server error occurred that prevented the request from being processed.
+|505 |HTTP VERSION NOT SUPPORTED |A server indicating that an unsupported version of HTTP is being used. Only HTTP/1.1 is supported.
 |=========================================================
 
 NOTE: Please refer to the link:https://tinkerpop.apache.org/docs/x.y.z/dev/io[IO Reference Documentation] for more
 examples of `RequestMessage` and `ResponseMessage` instances.
 
-NOTE: Tinkerpop provides a test server which may be useful for testing drivers. Details can be found
+NOTE: TinkerPop provides a test server which may be useful for testing drivers. Details can be found
 link:https://tinkerpop.apache.org/docs/current/dev/developer/#gremlin-socket-server-tests[here]
 
-=== OpProcessors Arguments
-
-The following sections define a non-exhaustive list of available operations and arguments for embedded `OpProcessors`
-(i.e. ones packaged with Gremlin Server).
-
-==== Common
+=== HTTP Request Interceptor
 
-All `OpProcessor` instances support these arguments.
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|batchSize |Int |When the result is an iterator this value defines the number of iterations each `ResponseMessage` should contain - overrides the `resultIterationBatchSize` server setting.
-|=========================================================
-
-==== Standard OpProcessor
-
-The "standard" `OpProcessor` handles requests for the primary function of Gremlin Server - executing Gremlin.
-Requests made to this `OpProcessor` are "sessionless" in the sense that a request must encapsulate the entirety
-of a transaction.  There is no state maintained between requests.  A transaction is started when the script is first
-evaluated and is committed when the script completes (or rolled back if an error occurred).
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |As this is the default `OpProcessor` this value can be set to an empty string.
-|op |[width="100%",cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`eval` !Evaluate a Gremlin script provided as a `String`.
-!=========================================================
-|=========================================================
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|saslMechanism |String | The SASL mechanism: `PLAIN` or `GSSAPI`. Note that it is up to the server implementation to use or disregard this setting (default implementation in Gremlin Server ignores it).
-|=========================================================
-
-**`eval` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The Gremlin script to evaluate.
-|bindings |Map |A map of key/value pairs to apply as variables in the context of the Gremlin script.
-|language |String |The flavor of Gremlin used (e.g. `gremlin-groovy`).
-|aliases |Map |A map of key/value pairs that allow globally bound `Graph` and `TraversalSource` objects to
-be aliased to different variable names for purposes of the current request.  The value represents the name of the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1` and `g2`, it would be possible
-to send an alias pair with key of "g" and value of "g2" and thus allow the script to refer to "g2" simply as "g".
-|evaluationTimeout |Long |An override for the server setting that determines the maximum time to wait for a script to execute on the server.
-|=========================================================
-
-==== Session OpProcessor
-
-The "session" `OpProcessor` handles requests for the primary function of Gremlin Server - executing Gremlin. It is
-like the "standard" `OpProcessor`, but instead maintains state between sessions and allows the option to leave all
-transaction management up to the calling client.  It is important that clients that open sessions, commit or roll
-them back, however Gremlin Server will try to clean up such things when a session is killed that has been abandoned.
-It is important to consider that a session can only be maintained with a single machine.  In the event that multiple
-Gremlin Server are deployed, session state is not shared among them.
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |This value should be set to `session`
-|op |
-[cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`eval` !Evaluate a Gremlin script provided as a `String`.
-!`close` !Deprecated. Gremlin-Server will only return a `NO CONTENT` message.
-|=========================================================
-
-NOTE: The "close" message related to sessions was deprecated as of 3.3.11. Closing sessions now relies on closing the connections. The function to accept `close` message on the server was removed
-in 3.5.0, but has been added back as of 3.5.2. Servers wishing to be compatible with older versions of the driver need only send back a `NO_CONTENT` for
-this message (which is what Gremlin Server does as of 3.5.0). Drivers wishing to be compatible with servers prior to
-3.3.11 may continue to send the message on calls to `close()`, otherwise such code can be removed.
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|saslMechanism |String | The SASL mechanism: `PLAIN` or `GSSAPI`. Note that it is up to the server implementation to use or disregard this setting (default implementation in Gremlin Server ignores it).
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|=========================================================
-
-**`eval` operation arguments**
-
-[width="100%",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The Gremlin script to evaluate.
-|session |String | *Required* The session identifier for the current session - typically this value should be a UUID (the session will be created if it doesn't exist).
-|manageTransaction |Boolean |When set to `true` the transaction for the current request is auto-committed or rolled-back as are done with sessionless requests - defaulted to `false`.
-|bindings |Map |A map of key/value pairs to apply as variables in the context of the Gremlin script.
-|evaluationTimeout |Long |An override for the server setting that determines the maximum time to wait for a script to execute on the server.
-|language |String |The flavor of Gremlin used (e.g. `gremlin-groovy`)
-|aliases |Map |A map of key/value pairs that allow globally bound `Graph` and `TraversalSource` objects to
-be aliased to different variable names for purposes of the current request.  The value represents the name the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1` and `g2`, it would be possible
-to send an alias pair with key of "g" and value of "g2" and thus allow the script to refer to "g2" simply as "g".
-|=========================================================
-
-**`close` operation arguments**
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|session |String | *Required* The session identifier for the session to close.
-|force |Boolean | Determines if the session should be force closed when the client is closed. Force closing will not
-attempt to close open transactions from existing running jobs and leave it to the underlying graph to decided how to
-proceed with those orphaned transactions. Setting this to `true` tends to lead to faster close operation and release
-of resources which can be desirable if Gremlin Server has a long session timeout and a long script evaluation timeout
-as attempts to close long run jobs can occur more rapidly. If not provided, this value is `false`.
-|=========================================================
-
-==== Traversal OpProcessor
-
-Both the Standard and Session OpProcessors allow for Gremlin scripts to be submitted to the server. The
-`TraversalOpProcessor` however allows Gremlin `Bytecode` to be submitted to the server. Supporting this `OpProcessor`
-makes it possible for a link:https://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-drivers-variants[Gremlin Language Variant]
-to submit a `Traversal` directly to Gremlin Server in the native language of the GLV without having to use a script in
-a different language.
-
-Unlike Standard and Session OpProcessors, the Traversal OpProcessor does not simply return the results of the
-`Traversal`. It instead returns `Traverser` objects which allows the client to take advantage of
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#barrier-step[bulking]. To describe this interaction more
-directly, the returned `Traverser` will represent some value from the `Traversal` result and the number of times it
-is represented in the full stream of results. So, if a `Traversal` happens to return the same vertex twenty times
-it won't return twenty instances of the same object. It will return one in `Traverser` with the `bulk` value set to
-twenty. Under this model, the amount of processing and network overhead can be reduced considerably.
-
-To demonstrate consider this example:
-
-[gremlin-groovy]
-----
-cluster = Cluster.open()
-client = cluster.connect()
-aliased = client.alias("g")
-g = traversal().with(org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph.instance())     <1>
-rs = aliased.submit(g.V().both().barrier().both().barrier()).all().get()                    <2>
-aliased.submit(g.V().both().barrier().both().barrier().count()).all().get().get(0).getInt() <3>
-rs.collect{[value: it.getObject().get(), bulk: it.getObject().bulk()]}                      <4>
-----
-
-<1> All commands through this step are just designed to demonstrate bulking with Gremlin Server and don't represent
-a real-world way that this feature would be used.
-<2> Submit a `Traversal` that happens to ensure that the server uses bulking. Note that a `Traverser` is returned
-and that there are only six results.
-<3> In actuality, however, if this same `Traversal` is iterated there are thirty results. Without bulking, the previous
-request would have sent back thirty traversers.
-<4> Note that the sum of the bulk of each `Traverser` is thirty.
-
-The full iteration of a `Traversal` is thus left to the client. It must interpret the bulk on the `Traverser` and
-unroll it to represent the actual number of times it exists when iterated. The unrolling is typically handled
-directly within TinkerPop's remote traversal implementations.
-
-[width="100%",cols="3,10a",options="header"]
-|=========================================================
-|Key |Description
-|processor |This value should be set to `traversal`
-|op |
-[cols="3,10",options="header"]
-!=========================================================
-!Key !Description
-!`authentication` !A request that contains the response to a server challenge for authentication.
-!`bytecode` !A request that contains the `Bytecode` representation of a `Traversal`.
-|=========================================================
-
-**`authentication` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|sasl |String | *Required* The response to the server authentication challenge.  This value is dependent on the SASL authentication mechanism required by the server and is Base64 encoded.
-|=========================================================
-
-**`bytecode` operation arguments**
-
-[width="100%",cols="2,2,9",options="header"]
-|=========================================================
-|Key |Type |Description
-|gremlin |String | *Required* The `Bytecode` representation of a `Traversal`.
-|aliases |Map | *Required* A map with a single key/value pair that refers to a globally bound `TraversalSource` object
-to be aliased to different variable names for purposes of the current request.  The value represents the name of the
-global variable and its key represents the new binding name as it will be referenced in the Gremlin query.  For
-example, if the Gremlin Server defines two `TraversalSource` instances named `g1`, it would be possible
-to send an alias pair with key of "g" and value of "g1" and thus allow the script to refer to "g1" simply as "g". Note
-that unlike users of `alias` in other contexts, in this case, the key can *only* be set to "g" and there can be only
-one key value pair present (since only one `Traversal` is being submitted, there is no sense to having more than a
-single alias).
-|=========================================================
+All graph drivers are expected to support HTTP request intercepting.  This means that the user of the graph driver

Review Comment:
   > All graph drivers are expected to support HTTP request intercepting.
   
   I think that statement is true of official TinkerPop drivers. that's an expectation we'd have. this documentation though is more of a guide for third-parties, so you are either:
   
   1. someone building a driver
   2. someone looking to build an interceptor
   
   if you are (1) then i dont think we want to say that folks must do this to be a compliant driver. If they don't do it, then they should be aware that they possibly close off access to certain providers who might require the interceptor to connect.  i think there is just a change of wording needed here. 
   
   if you are (2), i'm not sure you'd be here i guess. i suppose we have user docs in the drivers that cover this?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu merged PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864053112


##########
docs/src/dev/provider/index.asciidoc:
##########
@@ -54,6 +54,168 @@ This document attempts to address the needs of the different providers that have
 * Graph Language Provider
 * Graph Plugin Provider
 
+== HTTP API
+
+This section describes the TinkerPop HTTP API which should be implemented by both graph system providers and graph
+driver providers. There is only one endpoint that currently needs to be supported which is `POST /gremlin`. This
+endpoint is a Gremlin evaluator which takes in a Gremlin script request and responds with the serialized results. The
+formats below use a bit of pseudo-JSON to help represent request and response bodies. The actual format of the request
+and response bodies will be determined by the serializers defined via the "Accept" and "Content-Type" headers. As a
+result, a generic type definition in this document like "number" could translate to a "long" for a serializer that
+supports types like GraphBinary.
+
+=== HTTP Request Format
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+Accept: <mimetype>
+Content-Type: <mimetype>
+Gremlin-Hints: <hints>
+
+{
+  "gremlin": string,
+  "timeoutMs": number,
+  "bindings": object,
+  "g": string,
+  "language" : string,
+  "materializeProperties": string,
+  "bulked": boolean
+}
+----
+
+An actual, complete request might look like the following:
+
+[source,text]
+----
+POST /gremlin HTTP/1.1
+content-length: 61
+host: 127.0.0.1
+content-type: application/vnd.gremlin-v4.0+json
+accept-encoding: deflate
+accept: application/vnd.graphbinary-v4.0
+user-agent: NotAvailable Gremlin-Java.4.0.0 11.0.25 Windows_11.10.0 amd64
+{
+    "gremlin": "g.V()",
+    "language": "gremlin-lang"
+}
+----
+
+==== Expected Request HTTP Headers
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Name |Description |Required |Default
+|Accept |Serializer MIME types supported for the response. Must be a mimetype (see table below). |No |`application/vnd.gremlin-v4.0+json;types=false`
+|Accept-Encoding |The requested compression algorithm of the response. Valid values: `deflate`. |No |N/A
+|Authorization |Header used with Basic authorization. |No |N/A
+|Content-Length |The size of the payload |Yes |N/A
+|Content-Type |The MIME type of the serialized body |No |None
+|Gremlin-Hints |A semi-colon separated list of key/value pair metadata that could be helpful to the server in processing a particular request in some way. Must be a hints (see table below). |No |N/A
+|User-Agent |The user agent. Follow the format specified by <<user-agent-format, user agent format>>. |No |<<user-agent-format, user agent format>>
+|=========================================================
+
+==== Request Header Value Options
+
+[width="100%",cols="3,10",options="header"]
+|=========================================================
+|Name |Options
+|mimetype | application/vnd.gremlin-v4.0+json;types=false - GraphSON without embedded types
+|         | application/vnd.gremlin-v4.0+json;types=true - GraphSON with embedded types
+|         | application/vnd.graphbinary-v4.0 - GraphBinary with embedded types
+|hints | mutations: yes, no, unknown - Indicates if the Gremlin contains steps that can mutate the graph.
+|=========================================================
+
+The body of the request should be a `RequestMessage` which is a `Map`. The `RequestMessage` should be serialized using
+the serializer specified by the `Content-Type` header. The following are the key value pairs allowed in a
+`RequestMessage`:
+
+==== Request Message Format
+
+[width="100%",cols="3,10,3,3",options="header"]
+|=========================================================
+|Key |Description |Value |Required
+|gremlin |The Gremlin query to execute. |String containing script |Yes
+|timeoutMs |The maximum time a query is allowed to execute in milliseconds. |Number between 0 and 2^31-1 |No
+|bindings |Any bindings used to execute the query. |Object (Map) |No

Review Comment:
   Updated with more information on its interaction with "language" and how bindings are used based on it.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Update documentation around TinkerPop HTTP API and serializers. [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.

kenhuuu commented on code in PR #2908:
URL: https://github.com/apache/tinkerpop/pull/2908#discussion_r1864055068


##########
docs/src/dev/io/graphson.asciidoc:
##########
@@ -102,13 +104,11 @@ mime type is made explicit on requests to avoid breaking changes or unexpected r
 
 Version 4.0 of GraphSON was first introduced on TinkerPop 4.0.0 and is represented by the
 `application/vnd.gremlin-v4.0+json` mime type. There also exists an untyped version:
-`application/vnd.gremlin-v3.0+json;types=false`. It is very similar to GraphSON 3.0, with just several key differences:
+`application/vnd.gremlin-v4.0+json;types=false`. It is very similar to GraphSON 3.0, with just several key differences:

Review Comment:
   I think that part is supposed to say GraphSON 3.0.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org