mirror of
https://github.com/curl/curl.git
synced 2024-12-27 06:59:43 +08:00
d7b6ce64ce
This clarifies the handling of server responses by folding the code for
the complicated protocols into their protocol handlers. This concerns
mainly HTTP and its bastard sibling RTSP.
The terms "read" and "write" are often used without clear context if
they refer to the connect or the client/application side of a
transfer. This PR uses "read/write" for operations on the client side
and "send/receive" for the connection, e.g. server side. If this is
considered useful, we can revisit renaming of further methods in another
PR.
Curl's protocol handler `readwrite()` method been changed:
```diff
- CURLcode (*readwrite)(struct Curl_easy *data, struct connectdata *conn,
- const char *buf, size_t blen,
- size_t *pconsumed, bool *readmore);
+ CURLcode (*write_resp)(struct Curl_easy *data, const char *buf, size_t blen,
+ bool is_eos, bool *done);
```
The name was changed to clarify that this writes reponse data to the
client side. The parameter changes are:
* `conn` removed as it always operates on `data->conn`
* `pconsumed` removed as the method needs to handle all data on success
* `readmore` removed as no longer necessary
* `is_eos` as indicator that this is the last call for the transfer
response (end-of-stream).
* `done` TRUE on return iff the transfer response is to be treated as
finished
This change affects many files only because of updated comments in
handlers that provide no implementation. The real change is that the
HTTP protocol handlers now provide an implementation.
The HTTP protocol handlers `write_resp()` implementation will get passed
**all** raw data of a server response for the transfer. The HTTP/1.x
formatted status and headers, as well as the undecoded response
body. `Curl_http_write_resp_hds()` is used internally to parse the
response headers and pass them on. This method is public as the RTSP
protocol handler also uses it.
HTTP/1.1 "chunked" transport encoding is now part of the general
*content encoding* writer stack, just like other encodings. A new flag
`CLIENTWRITE_EOS` was added for the last client write. This allows
writers to verify that they are in a valid end state. The chunked
decoder will check if it indeed has seen the last chunk.
The general response handling in `transfer.c:466` happens in function
`readwrite_data()`. This mainly operates now like:
```
static CURLcode readwrite_data(data, ...)
{
do {
Curl_xfer_recv_resp(data, buf)
...
Curl_xfer_write_resp(data, buf)
...
} while(interested);
...
}
```
All the response data handling is implemented in
`Curl_xfer_write_resp()`. It calls the protocol handler's `write_resp()`
implementation if available, or does the default behaviour.
All raw response data needs to pass through this function. Which also
means that anyone in possession of such data may call
`Curl_xfer_write_resp()`.
Closes #12480
139 lines
4.8 KiB
C
139 lines
4.8 KiB
C
#ifndef HEADER_CURL_HTTP_CHUNKS_H
|
|
#define HEADER_CURL_HTTP_CHUNKS_H
|
|
/***************************************************************************
|
|
* _ _ ____ _
|
|
* Project ___| | | | _ \| |
|
|
* / __| | | | |_) | |
|
|
* | (__| |_| | _ <| |___
|
|
* \___|\___/|_| \_\_____|
|
|
*
|
|
* Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
*
|
|
* This software is licensed as described in the file COPYING, which
|
|
* you should have received as part of this distribution. The terms
|
|
* are also available at https://curl.se/docs/copyright.html.
|
|
*
|
|
* You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
* copies of the Software, and permit persons to whom the Software is
|
|
* furnished to do so, under the terms of the COPYING file.
|
|
*
|
|
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
* KIND, either express or implied.
|
|
*
|
|
* SPDX-License-Identifier: curl
|
|
*
|
|
***************************************************************************/
|
|
|
|
#ifndef CURL_DISABLE_HTTP
|
|
|
|
#include "dynbuf.h"
|
|
|
|
struct connectdata;
|
|
|
|
/*
|
|
* The longest possible hexadecimal number we support in a chunked transfer.
|
|
* Neither RFC2616 nor the later HTTP specs define a maximum chunk size.
|
|
* For 64 bit curl_off_t we support 16 digits. For 32 bit, 8 digits.
|
|
*/
|
|
#define CHUNK_MAXNUM_LEN (SIZEOF_CURL_OFF_T * 2)
|
|
|
|
typedef enum {
|
|
/* await and buffer all hexadecimal digits until we get one that isn't a
|
|
hexadecimal digit. When done, we go CHUNK_LF */
|
|
CHUNK_HEX,
|
|
|
|
/* wait for LF, ignore all else */
|
|
CHUNK_LF,
|
|
|
|
/* We eat the amount of data specified. When done, we move on to the
|
|
POST_CR state. */
|
|
CHUNK_DATA,
|
|
|
|
/* POSTLF should get a CR and then a LF and nothing else, then move back to
|
|
HEX as the CRLF combination marks the end of a chunk. A missing CR is no
|
|
big deal. */
|
|
CHUNK_POSTLF,
|
|
|
|
/* Used to mark that we're out of the game. NOTE: that there's a 'datasize'
|
|
field in the struct that will tell how many bytes that were not passed to
|
|
the client in the end of the last buffer! */
|
|
CHUNK_STOP,
|
|
|
|
/* At this point optional trailer headers can be found, unless the next line
|
|
is CRLF */
|
|
CHUNK_TRAILER,
|
|
|
|
/* A trailer CR has been found - next state is CHUNK_TRAILER_POSTCR.
|
|
Next char must be a LF */
|
|
CHUNK_TRAILER_CR,
|
|
|
|
/* A trailer LF must be found now, otherwise CHUNKE_BAD_CHUNK will be
|
|
signalled If this is an empty trailer CHUNKE_STOP will be signalled.
|
|
Otherwise the trailer will be broadcasted via Curl_client_write() and the
|
|
next state will be CHUNK_TRAILER */
|
|
CHUNK_TRAILER_POSTCR,
|
|
|
|
/* Successfully de-chunked everything */
|
|
CHUNK_DONE,
|
|
|
|
/* Failed on seeing a bad or not correctly terminated chunk */
|
|
CHUNK_FAILED
|
|
} ChunkyState;
|
|
|
|
typedef enum {
|
|
CHUNKE_OK = 0,
|
|
CHUNKE_TOO_LONG_HEX = 1,
|
|
CHUNKE_ILLEGAL_HEX,
|
|
CHUNKE_BAD_CHUNK,
|
|
CHUNKE_BAD_ENCODING,
|
|
CHUNKE_OUT_OF_MEMORY,
|
|
CHUNKE_PASSTHRU_ERROR /* Curl_httpchunk_read() returns a CURLcode to use */
|
|
} CHUNKcode;
|
|
|
|
struct Curl_chunker {
|
|
curl_off_t datasize;
|
|
ChunkyState state;
|
|
CHUNKcode last_code;
|
|
struct dynbuf trailer; /* for chunked-encoded trailer */
|
|
unsigned char hexindex;
|
|
char hexbuffer[CHUNK_MAXNUM_LEN + 1]; /* +1 for null-terminator */
|
|
BIT(ignore_body); /* never write response body data */
|
|
};
|
|
|
|
/* The following functions are defined in http_chunks.c */
|
|
void Curl_httpchunk_init(struct Curl_easy *data, struct Curl_chunker *ch,
|
|
bool ignore_body);
|
|
void Curl_httpchunk_free(struct Curl_easy *data, struct Curl_chunker *ch);
|
|
void Curl_httpchunk_reset(struct Curl_easy *data, struct Curl_chunker *ch,
|
|
bool ignore_body);
|
|
|
|
/*
|
|
* Read BODY bytes in HTTP/1.1 chunked encoding from `buf` and return
|
|
* the amount of bytes consumed. The actual response bytes and trailer
|
|
* headers are written out to the client.
|
|
* On success, this will consume all bytes up to the end of the response,
|
|
* e.g. the last chunk, has been processed.
|
|
* @param data the transfer involved
|
|
* @param ch the chunker instance keeping state across calls
|
|
* @param buf the response data
|
|
* @param blen amount of bytes in `buf`
|
|
* @param pconsumed on successful return, the number of bytes in `buf`
|
|
* consumed
|
|
*
|
|
* This function always uses ASCII hex values to accommodate non-ASCII hosts.
|
|
* For example, 0x0d and 0x0a are used instead of '\r' and '\n'.
|
|
*/
|
|
CURLcode Curl_httpchunk_read(struct Curl_easy *data, struct Curl_chunker *ch,
|
|
char *buf, size_t blen, size_t *pconsumed);
|
|
|
|
/**
|
|
* @return TRUE iff chunked decoded has finished successfully.
|
|
*/
|
|
bool Curl_httpchunk_is_done(struct Curl_easy *data, struct Curl_chunker *ch);
|
|
|
|
extern const struct Curl_cwtype Curl_httpchunk_unencoder;
|
|
|
|
#endif /* !CURL_DISABLE_HTTP */
|
|
|
|
#endif /* HEADER_CURL_HTTP_CHUNKS_H */
|