From 949216f5839bc79d027f0ac4c1c4fb83a8f4cbd0 Mon Sep 17 00:00:00 2001 From: Sean McArthur Date: Thu, 16 Sep 2021 10:00:38 -0700 Subject: [PATCH] docs(ffi): expand URI documentation --- capi/include/hyper.h | 13 +++++++++++++ src/ffi/http_types.rs | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/capi/include/hyper.h b/capi/include/hyper.h index 7d79825865..efe5f06106 100644 --- a/capi/include/hyper.h +++ b/capi/include/hyper.h @@ -425,6 +425,19 @@ enum hyper_code hyper_request_set_method(struct hyper_request *req, /* Set the URI of the request. + + The request's URI is best described as the `request-target` from the RFCs. So in HTTP/1, + whatever is set will get sent as-is in the first line (GET $uri HTTP/1.1). It + supports the 4 defined variants, origin-form, absolute-form, authority-form, and + asterisk-form. + + The underlying type was built to efficiently support HTTP/2 where the request-target is + split over :scheme, :authority, and :path. As such, each part can be set explicitly, or the + type can parse a single contiguous string and if a scheme is found, that slot is "set". If + the string just starts with a path, only the path portion is set. All pseudo headers that + have been parsed/set are sent when the connection type is HTTP/2. + + To set each slot explicitly, use `hyper_request_set_uri_parts`. */ enum hyper_code hyper_request_set_uri(struct hyper_request *req, const uint8_t *uri, diff --git a/src/ffi/http_types.rs b/src/ffi/http_types.rs index c80d67fd2b..f6d32947bf 100644 --- a/src/ffi/http_types.rs +++ b/src/ffi/http_types.rs @@ -73,6 +73,19 @@ ffi_fn! { ffi_fn! { /// Set the URI of the request. + /// + /// The request's URI is best described as the `request-target` from the RFCs. So in HTTP/1, + /// whatever is set will get sent as-is in the first line (GET $uri HTTP/1.1). It + /// supports the 4 defined variants, origin-form, absolute-form, authority-form, and + /// asterisk-form. + /// + /// The underlying type was built to efficiently support HTTP/2 where the request-target is + /// split over :scheme, :authority, and :path. As such, each part can be set explicitly, or the + /// type can parse a single contiguous string and if a scheme is found, that slot is "set". If + /// the string just starts with a path, only the path portion is set. All pseudo headers that + /// have been parsed/set are sent when the connection type is HTTP/2. + /// + /// To set each slot explicitly, use `hyper_request_set_uri_parts`. fn hyper_request_set_uri(req: *mut hyper_request, uri: *const u8, uri_len: size_t) -> hyper_code { let bytes = unsafe { std::slice::from_raw_parts(uri, uri_len as usize)