From bca140bceda7aabc3bd1ecd79abd106cc2ab43f7 Mon Sep 17 00:00:00 2001
From: tan <tanmaykm@gmail.com>
Date: Mon, 28 Aug 2023 20:26:43 +0530
Subject: [PATCH] update docs, increment version

Updated docs for recent changes.
Incremented patch version for tagging.
---
 Project.toml          |  2 +-
 docs/src/userguide.md | 23 +++++++++++++++++++++++
 src/client.jl         |  1 +
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/Project.toml b/Project.toml
index 6e3dd0a..e9cbf03 100644
--- a/Project.toml
+++ b/Project.toml
@@ -4,7 +4,7 @@ keywords = ["Swagger", "OpenAPI", "REST"]
 license = "MIT"
 desc = "OpenAPI server and client helper for Julia"
 authors = ["JuliaHub Inc."]
-version = "0.1.16"
+version = "0.1.17"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
diff --git a/docs/src/userguide.md b/docs/src/userguide.md
index eb426ff..65c542e 100644
--- a/docs/src/userguide.md
+++ b/docs/src/userguide.md
@@ -124,6 +124,8 @@ Client(root::String;
     timeout::Int=DEFAULT_TIMEOUT_SECS,
     long_polling_timeout::Int=DEFAULT_LONGPOLL_TIMEOUT_SECS,
     pre_request_hook::Function,
+    escape_path_params::Union{Nothing,Bool}=nothing,
+    chunk_reader_type::Union{Nothing,Type{<:AbstractChunkReader}}=nothing,
     verbose::Union{Bool,Function}=false,
 )
 ```
@@ -136,12 +138,16 @@ Where:
 - `timeout`: optional timeout to apply for server methods (default `OpenAPI.Clients.DEFAULT_TIMEOUT_SECS`)
 - `long_polling_timeout`: optional timeout to apply for long polling methods (default `OpenAPI.Clients.DEFAULT_LONGPOLL_TIMEOUT_SECS`)
 - `pre_request_hook`: user provided hook to modify the request before it is sent
+- `escape_path_params`: Whether the path parameters should be escaped before being used in the URL (true by default). This is useful if the path parameters contain characters that are not allowed in URLs or contain path separators themselves.
+- `chunk_reader_type`: The type of chunk reader to be used for streaming responses.
 - `verbose`: whether to enable verbose logging
 
 The `pre_request_hook` must provide the following two implementations:
 - `pre_request_hook(ctx::OpenAPI.Clients.Ctx) -> ctx`
 - `pre_request_hook(resource_path::AbstractString, body::Any, headers::Dict{String,String}) -> (resource_path, body, headers)`
 
+The `chunk_reader_type` can be one of `LineChunkReader`, `JSONChunkReader` or `RFC7464ChunkReader`. If not specified, then the type is automatically determined based on the return type of the API call. Refer to the [Streaming Responses](#Streaming-Responses) section for more details.
+
 The `verbose` option can be one of:
 - `false`: the default, no verbose logging
 - `true`: enables curl verbose logging to stderr
@@ -191,3 +197,20 @@ Optional middlewares can be one or more of:
 
 The order in which middlewares are invoked is:
 `init |> read |> pre_validation |> validate |> pre_invoke |> invoke |> post_invoke`
+
+## Streaming Responses
+
+Some OpenAPI implementations implement streaming of responses by sending more than one items in the response, each of which is of the type declared as the return type in the specification. E.g. the [Twitter OpenAPI specification](https://api.twitter.com/2/openapi.json) that keeps sending tweets in JSON like this forever:
+
+```json
+{"data":{"id":"1800000000000000000","text":"mmm i like a sandwich"},"matching_rules":[{"id":1800000000000000000,"tag":"\"sandwich\""}]}
+{"data":{"id":"1800000000000000001","text":"lets have a sandwich"},"matching_rules":[{"id":1800000000000000001,"tag":"\"sandwich\""}]}
+```
+
+OpenAPI.jl handles such responses through "chunk readers" which are engaged only with the streaming API endpoints. There can be multiple implementations of chunk readers, each of which must be of type `AbstractChunkReader`. The following are the chunk readers provided, each with a different chunk detection strategy. They are selected based on some heuristics based on the response data type.
+
+- `LineChunkReader`: Chunks delimited by newline. This is the default when the response type is detected to be not of `OpenAPI.APIModel` type.
+- `JSONChunkReader`: Each chunk is a JSON. Whitespaces between JSONs are ignored. This is the default when the response type is detected to be a `OpenAPI.APIModel`.
+- `RFC7464ChunkReader`: A reader based on [RFC 7464](https://www.rfc-editor.org/rfc/rfc7464.html). Available for use by overriding through `Client` or `Ctx`.
+
+The `OpenAPI.Clients.Client` and `OpenAPI.Clients.Ctx` constructors take an additional `chunk_reader_type` keyword parameter. This can be one of `OpenAPI.Clients.LineChunkReader`, `OpenAPI.Clients.JSONChunkReader` or `OpenAPI.Clients.RFC7464ChunkReader`. If not specified, then the type is automatically determined as described above.
diff --git a/src/client.jl b/src/client.jl
index da138e1..647ef27 100644
--- a/src/client.jl
+++ b/src/client.jl
@@ -107,6 +107,7 @@ end
         timeout::Int=DEFAULT_TIMEOUT_SECS,
         pre_request_hook::Function=noop_pre_request_hook,
         escape_path_params::Union{Nothing,Bool}=nothing,
+        chunk_reader_type::Union{Nothing,Type{<:AbstractChunkReader}}=nothing,
         verbose::Union{Bool,Function}=false,
     )