sandboxed-api/oss-internship-2020/curl/README.md

122 lines
4.5 KiB
Markdown
Raw Normal View History

Copybara import of the project: Including changes for GitHub -> internal migration -- b5d7e43ddeff9c087d0f67949bea6ac795c5474a by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Initial curl commit -- 24786c44d89b4a6817204aaacd84fc1aa2747434 by Federico Stazi <fstazi@google.com>: Added gitignore and curl submodule -- 6d5cfd575abd05c387f93be060c8fc88fd39e482 by Federico Stazi <fstazi@google.com>: Added new line at the end of files -- c7423c5f8a8d460655d0fafa198758c39d5270d1 by Federico Stazi <fstazi@google.com>: Remove SHARED from add_sapi_library -- 05c0a4b004feba1c0ae1ba6bf519966f48589ba6 by Federico Stazi <fstazi@google.com>: Fix includes -- 5be51fabbef7e7eab032dbfb94239654e44008c3 by Federico Stazi <fstazi@google.com>: Improve comments -- 34338411b845d438a5b7615d990d6539771152eb by Federico Stazi <fstazi@google.com>: Improve style -- 8c68ac221ff158aab3b285d8b2d6158a895ddbf2 by Federico Stazi <fstazi@google.com>: Address review comments -- ac1112ae4de6f5f520054b5608d202a57c296ac4 by Federico Stazi <fstazi@google.com>: Minor fix -- f47e1cc6aceb0365cb2e5352d61980628af7f954 by Federico Stazi <fstazi@google.com>: Implement all curl methods -- 929123127532589ef19f12114b8e450cc2c976a1 by Federico Stazi <fstazi@google.com>: Address reviews and improve code style -- 1b0a8edfd4cdffdc76f3e979a5e1b42cbe289e73 by Federico Stazi <fstazi@google.com>: Minor fix -- cea046d3e29b86e04bd6ce7821ee1409cea2db37 by Federico Stazi <fstazi@google.com>: Implement stricter policy -- cf23888b88b71add3e60524f3db3604f0ab6c386 by Federico Stazi <fstazi@google.com>: Improve and extend examples -- 6167cafbdec1355588c073baa8cdf17fad1fcb9e by Federico Stazi <fstazi@google.com>: Implement tests -- 9fed2ec09798e656cd5c518bc13f45eea1abef2e by Federico Stazi <fstazi@google.com>: Improved error handling -- e446ec81a13d3c567bdebe00285211d9df9dbed1 by Federico Stazi <fstazi@google.com>: Address review comments -- cf41ec4701a6a47ecee3af6765623ca020cebfcd by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Fix project name -- 9a4293a3cfd87b9b13b46a36d5eeee9d575ea519 by Federico Stazi <fstazi@google.com>: Fix project name -- bbebeee1a69fed2c70afc6afa2aa79aad990a778 by Federico Stazi <fstazi@google.com>: Fix test mock server -- eb783de3f5fc35877db5f08fd53c9a33207a416e by Federico Stazi <fstazi@google.com>: Address review comments -- cf6cb89bca2b0275652509afdb4d4e20e9e851ba by Federico Stazi <fstazi@google.com>: Minor mock server fix -- b52d9e6e4fa1f9c07a3027b4b4d564457e7a648f by Federico Stazi <fstazi@google.com>: Address review comments PiperOrigin-RevId: 333292204 Change-Id: I9ff27348028d9f22486492dc92c0859ff8f44d68
2020-09-23 22:59:42 +08:00
# LibCurl Sandbox
This library is a sandboxed version of curl's C API,
[libcurl](https://curl.haxx.se/libcurl/c/), implemented using Sandboxed API.
## Setup
The repository can be cloned using: `git clone --recursive [URL to this repo]`
The `--recursive` flag ensures that submodules are also cloned.
Alternatively, if the repository has already been cloned but the submodules have
not, these can be cloned using: `git submodule update --init --recursive`
The full list of Sandboxed API dependencies can be found on
[Sandboxed API Getting Started page](https://developers.google.com/sandboxed-api/docs/getting-started).
The following commands, used from the current `curl/` directory, build the
library: `mkdir -p build cd build cmake .. -G Ninja -D SAPI_ROOT=[path to
sandboxed-api] cmake --build .`
## Implementation details
All of libcurl's methods are supported by the library. However, a few of these
have different signatures defined in the sandboxed header `custom_curl.h`, which
wraps and extends libcurl.
This is necessary because Sandboxed API sandboxes most of libcurl correctly, but
encounters some issues when sandboxing a few methods. The simplest solution is
wrapping these methods into wrapper methods that accomplish the same tasks but
can also be sandboxed.
The next sections describe the issues encountered and contain some information
on the signatures of the wrapper methods solving these issues.
#### Variadic methods
Variadic methods are currently not supported by Sandboxed API. To solve this,
these methods are defined with an additional explicit parameter in
`custom_curl.h`.
The methods are:
- `curl_easy_setopt`. Use `curl_easy_setopt_ptr`, `curl_easy_setopt_long` or
`curl_easy_setopt_curl_off_t` instead.
- `curl_easy_getinfo`. Use `curl_easy_getinfo_ptr` instead.
- `curl_multi_setopt`. Use `curl_multi_setopt_ptr`, `curl_multi_setopt_long`
or `curl_multi_setopt_curl_off_t` instead.
- `curl_share_setopt`. Use `curl_share_setopt_ptr` or `curl_share_setopt_long`
instead
Copybara import of the project: Including changes for GitHub -> internal migration -- b5d7e43ddeff9c087d0f67949bea6ac795c5474a by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Initial curl commit -- 24786c44d89b4a6817204aaacd84fc1aa2747434 by Federico Stazi <fstazi@google.com>: Added gitignore and curl submodule -- 6d5cfd575abd05c387f93be060c8fc88fd39e482 by Federico Stazi <fstazi@google.com>: Added new line at the end of files -- c7423c5f8a8d460655d0fafa198758c39d5270d1 by Federico Stazi <fstazi@google.com>: Remove SHARED from add_sapi_library -- 05c0a4b004feba1c0ae1ba6bf519966f48589ba6 by Federico Stazi <fstazi@google.com>: Fix includes -- 5be51fabbef7e7eab032dbfb94239654e44008c3 by Federico Stazi <fstazi@google.com>: Improve comments -- 34338411b845d438a5b7615d990d6539771152eb by Federico Stazi <fstazi@google.com>: Improve style -- 8c68ac221ff158aab3b285d8b2d6158a895ddbf2 by Federico Stazi <fstazi@google.com>: Address review comments -- ac1112ae4de6f5f520054b5608d202a57c296ac4 by Federico Stazi <fstazi@google.com>: Minor fix -- f47e1cc6aceb0365cb2e5352d61980628af7f954 by Federico Stazi <fstazi@google.com>: Implement all curl methods -- 929123127532589ef19f12114b8e450cc2c976a1 by Federico Stazi <fstazi@google.com>: Address reviews and improve code style -- 1b0a8edfd4cdffdc76f3e979a5e1b42cbe289e73 by Federico Stazi <fstazi@google.com>: Minor fix -- cea046d3e29b86e04bd6ce7821ee1409cea2db37 by Federico Stazi <fstazi@google.com>: Implement stricter policy -- cf23888b88b71add3e60524f3db3604f0ab6c386 by Federico Stazi <fstazi@google.com>: Improve and extend examples -- 6167cafbdec1355588c073baa8cdf17fad1fcb9e by Federico Stazi <fstazi@google.com>: Implement tests -- 9fed2ec09798e656cd5c518bc13f45eea1abef2e by Federico Stazi <fstazi@google.com>: Improved error handling -- e446ec81a13d3c567bdebe00285211d9df9dbed1 by Federico Stazi <fstazi@google.com>: Address review comments -- cf41ec4701a6a47ecee3af6765623ca020cebfcd by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Fix project name -- 9a4293a3cfd87b9b13b46a36d5eeee9d575ea519 by Federico Stazi <fstazi@google.com>: Fix project name -- bbebeee1a69fed2c70afc6afa2aa79aad990a778 by Federico Stazi <fstazi@google.com>: Fix test mock server -- eb783de3f5fc35877db5f08fd53c9a33207a416e by Federico Stazi <fstazi@google.com>: Address review comments -- cf6cb89bca2b0275652509afdb4d4e20e9e851ba by Federico Stazi <fstazi@google.com>: Minor mock server fix -- b52d9e6e4fa1f9c07a3027b4b4d564457e7a648f by Federico Stazi <fstazi@google.com>: Address review comments PiperOrigin-RevId: 333292204 Change-Id: I9ff27348028d9f22486492dc92c0859ff8f44d68
2020-09-23 22:59:42 +08:00
#### Methods with incomplete array arguments
Incomplete array arguments are currently not supported by Sandboxed API. To
solve this, methods taking an incomplete array argument have a wrapper in
`custom_curl.h`, and take a pointer as the argument.
The methods are:
- `curl_multi_poll`. Use `curl_multi_poll_sapi` instead.
- `curl_multi_wait`. Use `curl_multi_wait_sapi` instead.
Copybara import of the project: Including changes for GitHub -> internal migration -- b5d7e43ddeff9c087d0f67949bea6ac795c5474a by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Initial curl commit -- 24786c44d89b4a6817204aaacd84fc1aa2747434 by Federico Stazi <fstazi@google.com>: Added gitignore and curl submodule -- 6d5cfd575abd05c387f93be060c8fc88fd39e482 by Federico Stazi <fstazi@google.com>: Added new line at the end of files -- c7423c5f8a8d460655d0fafa198758c39d5270d1 by Federico Stazi <fstazi@google.com>: Remove SHARED from add_sapi_library -- 05c0a4b004feba1c0ae1ba6bf519966f48589ba6 by Federico Stazi <fstazi@google.com>: Fix includes -- 5be51fabbef7e7eab032dbfb94239654e44008c3 by Federico Stazi <fstazi@google.com>: Improve comments -- 34338411b845d438a5b7615d990d6539771152eb by Federico Stazi <fstazi@google.com>: Improve style -- 8c68ac221ff158aab3b285d8b2d6158a895ddbf2 by Federico Stazi <fstazi@google.com>: Address review comments -- ac1112ae4de6f5f520054b5608d202a57c296ac4 by Federico Stazi <fstazi@google.com>: Minor fix -- f47e1cc6aceb0365cb2e5352d61980628af7f954 by Federico Stazi <fstazi@google.com>: Implement all curl methods -- 929123127532589ef19f12114b8e450cc2c976a1 by Federico Stazi <fstazi@google.com>: Address reviews and improve code style -- 1b0a8edfd4cdffdc76f3e979a5e1b42cbe289e73 by Federico Stazi <fstazi@google.com>: Minor fix -- cea046d3e29b86e04bd6ce7821ee1409cea2db37 by Federico Stazi <fstazi@google.com>: Implement stricter policy -- cf23888b88b71add3e60524f3db3604f0ab6c386 by Federico Stazi <fstazi@google.com>: Improve and extend examples -- 6167cafbdec1355588c073baa8cdf17fad1fcb9e by Federico Stazi <fstazi@google.com>: Implement tests -- 9fed2ec09798e656cd5c518bc13f45eea1abef2e by Federico Stazi <fstazi@google.com>: Improved error handling -- e446ec81a13d3c567bdebe00285211d9df9dbed1 by Federico Stazi <fstazi@google.com>: Address review comments -- cf41ec4701a6a47ecee3af6765623ca020cebfcd by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Fix project name -- 9a4293a3cfd87b9b13b46a36d5eeee9d575ea519 by Federico Stazi <fstazi@google.com>: Fix project name -- bbebeee1a69fed2c70afc6afa2aa79aad990a778 by Federico Stazi <fstazi@google.com>: Fix test mock server -- eb783de3f5fc35877db5f08fd53c9a33207a416e by Federico Stazi <fstazi@google.com>: Address review comments -- cf6cb89bca2b0275652509afdb4d4e20e9e851ba by Federico Stazi <fstazi@google.com>: Minor mock server fix -- b52d9e6e4fa1f9c07a3027b4b4d564457e7a648f by Federico Stazi <fstazi@google.com>: Address review comments PiperOrigin-RevId: 333292204 Change-Id: I9ff27348028d9f22486492dc92c0859ff8f44d68
2020-09-23 22:59:42 +08:00
#### Methods with conflicts on the generated header
Some methods create conflicts on the generated header because of redefined
`#define` directives from files included by the header. To solve this, the
conflicting types and methods are redefined in `custom_curl.h`.
The types are:
- `time_t`. Use `time_t_sapi` instead.
- `fd_set`. Use `fd_set_sapi` instead.
The methods are:
Copybara import of the project: Including changes for GitHub -> internal migration -- b5d7e43ddeff9c087d0f67949bea6ac795c5474a by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Initial curl commit -- 24786c44d89b4a6817204aaacd84fc1aa2747434 by Federico Stazi <fstazi@google.com>: Added gitignore and curl submodule -- 6d5cfd575abd05c387f93be060c8fc88fd39e482 by Federico Stazi <fstazi@google.com>: Added new line at the end of files -- c7423c5f8a8d460655d0fafa198758c39d5270d1 by Federico Stazi <fstazi@google.com>: Remove SHARED from add_sapi_library -- 05c0a4b004feba1c0ae1ba6bf519966f48589ba6 by Federico Stazi <fstazi@google.com>: Fix includes -- 5be51fabbef7e7eab032dbfb94239654e44008c3 by Federico Stazi <fstazi@google.com>: Improve comments -- 34338411b845d438a5b7615d990d6539771152eb by Federico Stazi <fstazi@google.com>: Improve style -- 8c68ac221ff158aab3b285d8b2d6158a895ddbf2 by Federico Stazi <fstazi@google.com>: Address review comments -- ac1112ae4de6f5f520054b5608d202a57c296ac4 by Federico Stazi <fstazi@google.com>: Minor fix -- f47e1cc6aceb0365cb2e5352d61980628af7f954 by Federico Stazi <fstazi@google.com>: Implement all curl methods -- 929123127532589ef19f12114b8e450cc2c976a1 by Federico Stazi <fstazi@google.com>: Address reviews and improve code style -- 1b0a8edfd4cdffdc76f3e979a5e1b42cbe289e73 by Federico Stazi <fstazi@google.com>: Minor fix -- cea046d3e29b86e04bd6ce7821ee1409cea2db37 by Federico Stazi <fstazi@google.com>: Implement stricter policy -- cf23888b88b71add3e60524f3db3604f0ab6c386 by Federico Stazi <fstazi@google.com>: Improve and extend examples -- 6167cafbdec1355588c073baa8cdf17fad1fcb9e by Federico Stazi <fstazi@google.com>: Implement tests -- 9fed2ec09798e656cd5c518bc13f45eea1abef2e by Federico Stazi <fstazi@google.com>: Improved error handling -- e446ec81a13d3c567bdebe00285211d9df9dbed1 by Federico Stazi <fstazi@google.com>: Address review comments -- cf41ec4701a6a47ecee3af6765623ca020cebfcd by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Fix project name -- 9a4293a3cfd87b9b13b46a36d5eeee9d575ea519 by Federico Stazi <fstazi@google.com>: Fix project name -- bbebeee1a69fed2c70afc6afa2aa79aad990a778 by Federico Stazi <fstazi@google.com>: Fix test mock server -- eb783de3f5fc35877db5f08fd53c9a33207a416e by Federico Stazi <fstazi@google.com>: Address review comments -- cf6cb89bca2b0275652509afdb4d4e20e9e851ba by Federico Stazi <fstazi@google.com>: Minor mock server fix -- b52d9e6e4fa1f9c07a3027b4b4d564457e7a648f by Federico Stazi <fstazi@google.com>: Address review comments PiperOrigin-RevId: 333292204 Change-Id: I9ff27348028d9f22486492dc92c0859ff8f44d68
2020-09-23 22:59:42 +08:00
- `curl_getdate`. Use `curl_getdate_sapi` instead.
- `curl_multi_fdset`. Use `curl_multi_fdset_sapi` instead.
Copybara import of the project: Including changes for GitHub -> internal migration -- b5d7e43ddeff9c087d0f67949bea6ac795c5474a by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Initial curl commit -- 24786c44d89b4a6817204aaacd84fc1aa2747434 by Federico Stazi <fstazi@google.com>: Added gitignore and curl submodule -- 6d5cfd575abd05c387f93be060c8fc88fd39e482 by Federico Stazi <fstazi@google.com>: Added new line at the end of files -- c7423c5f8a8d460655d0fafa198758c39d5270d1 by Federico Stazi <fstazi@google.com>: Remove SHARED from add_sapi_library -- 05c0a4b004feba1c0ae1ba6bf519966f48589ba6 by Federico Stazi <fstazi@google.com>: Fix includes -- 5be51fabbef7e7eab032dbfb94239654e44008c3 by Federico Stazi <fstazi@google.com>: Improve comments -- 34338411b845d438a5b7615d990d6539771152eb by Federico Stazi <fstazi@google.com>: Improve style -- 8c68ac221ff158aab3b285d8b2d6158a895ddbf2 by Federico Stazi <fstazi@google.com>: Address review comments -- ac1112ae4de6f5f520054b5608d202a57c296ac4 by Federico Stazi <fstazi@google.com>: Minor fix -- f47e1cc6aceb0365cb2e5352d61980628af7f954 by Federico Stazi <fstazi@google.com>: Implement all curl methods -- 929123127532589ef19f12114b8e450cc2c976a1 by Federico Stazi <fstazi@google.com>: Address reviews and improve code style -- 1b0a8edfd4cdffdc76f3e979a5e1b42cbe289e73 by Federico Stazi <fstazi@google.com>: Minor fix -- cea046d3e29b86e04bd6ce7821ee1409cea2db37 by Federico Stazi <fstazi@google.com>: Implement stricter policy -- cf23888b88b71add3e60524f3db3604f0ab6c386 by Federico Stazi <fstazi@google.com>: Improve and extend examples -- 6167cafbdec1355588c073baa8cdf17fad1fcb9e by Federico Stazi <fstazi@google.com>: Implement tests -- 9fed2ec09798e656cd5c518bc13f45eea1abef2e by Federico Stazi <fstazi@google.com>: Improved error handling -- e446ec81a13d3c567bdebe00285211d9df9dbed1 by Federico Stazi <fstazi@google.com>: Address review comments -- cf41ec4701a6a47ecee3af6765623ca020cebfcd by Federico Stazi <34340238+FedericoStazi@users.noreply.github.com>: Fix project name -- 9a4293a3cfd87b9b13b46a36d5eeee9d575ea519 by Federico Stazi <fstazi@google.com>: Fix project name -- bbebeee1a69fed2c70afc6afa2aa79aad990a778 by Federico Stazi <fstazi@google.com>: Fix test mock server -- eb783de3f5fc35877db5f08fd53c9a33207a416e by Federico Stazi <fstazi@google.com>: Address review comments -- cf6cb89bca2b0275652509afdb4d4e20e9e851ba by Federico Stazi <fstazi@google.com>: Minor mock server fix -- b52d9e6e4fa1f9c07a3027b4b4d564457e7a648f by Federico Stazi <fstazi@google.com>: Address review comments PiperOrigin-RevId: 333292204 Change-Id: I9ff27348028d9f22486492dc92c0859ff8f44d68
2020-09-23 22:59:42 +08:00
#### Function pointers
The functions whose pointers will be passed to the library's methods
(*callbacks*) can't be implemented in the files making use of the library, but
must be in other files. These files must be compiled together with the library,
and this is done by adding their absolute path to the cmake variable
`CURL_SAPI_CALLBACKS`.
The pointers can then be obtained using an `RPCChannel` object, as shown in
`example2.cc`.
## Examples
The `examples` directory contains the sandboxed versions of example source codes
taken from [this page](https://curl.haxx.se/libcurl/c/example.html) on curl's
website. More information about each example can be found in the examples'
[README](examples/README.md).
To build these examples when building the library, the cmake variable
`CURL_SAPI_ENABLE_EXAMPLES` must be set to `ON`. This enables Sandboxed API
examples as well.
## Policy
The `sandbox.h` file contains a policy allowing all is necessary for libcurl to
perform simple requests. It is used by all the examples, except by example3.
This example needs some additional policies and files in its namespace (since it
uses HTTPS), and the file `example3.cc` shows how to easily extend an existing
policy.
## Testing
The `tests` folder contains some test cases created using Google Test. The class
`CurlTestUtils` is used to facilitate some tasks that all test cases need,
including the setup of a mock local server on which test requests are performed.
To build these tests when building the library, the cmake variable
`CURL_SAPI_ENABLE_TESTS` must be set to `ON`. This enables Sandboxed API tests
as well.
## Callbacks
The `callbacks.h` and `callbacks.cc` files implement all the callbacks used by
examples and tests.