访问http:h2

学习如何访问Http2。

示例

example/http_c++

关于h2

brpc把HTTP/2协议统称为”h2”,不论是否加密。然而未开启ssl的HTTP/2连接在/connections中会按官方名称h2c显示,而开启ssl的会显示为h2。

brpc中http和h2的编程接口基本没有区别。除非特殊说明,所有提到的http特性都同时对h2有效。

创建Channel

brpc::Channel可访问http/h2服务,ChannelOptions.protocol须指定为PROTOCOL_HTTP或PROTOCOL_H2。

设定好协议后,Channel::Init的第一个参数可为任意合法的URL。注意:允许任意URL是为了省去用户取出host和port的麻烦,Channel::Init只用其中的host及port,其他部分都会丢弃。

  1. brpc::ChannelOptions options;
  2. options.protocol = brpc::PROTOCOL_HTTP; // or brpc::PROTOCOL_H2
  3. if (channel.Init("www.baidu.com" /*any url*/, &options) != 0) {
  4. LOG(ERROR) << "Fail to initialize channel";
  5. return -1;
  6. }

http/h2 channel也支持bns地址或其他NamingService。

GET

  1. brpc::Controller cntl;
  2. cntl.http_request().uri() = "www.baidu.com/index.html"; // 设置为待访问的URL
  3. channel.CallMethod(NULL, &cntl, NULL, NULL, NULL/*done*/);

HTTP/h2和protobuf关系不大,所以除了Controller和done,CallMethod的其他参数均为NULL。如果要异步操作,最后一个参数传入done。

cntl.response_attachment()是回复的body,类型也是butil::IOBuf。IOBuf可通过to_string()转化为std::string,但是需要分配内存并拷贝所有内容,如果关注性能,处理过程应直接支持IOBuf,而不要求连续内存。

POST

默认的HTTP Method为GET,可设置为POST或更多http method。待POST的数据应置入request_attachment(),它(butil::IOBuf)可以直接append std::string或char*。

  1. brpc::Controller cntl;
  2. cntl.http_request().uri() = "..."; // 设置为待访问的URL
  3. cntl.http_request().set_method(brpc::HTTP_METHOD_POST);
  4. cntl.request_attachment().append("{\"message\":\"hello world!\"}");
  5. channel.CallMethod(NULL, &cntl, NULL, NULL, NULL/*done*/);

需要大量打印过程的body建议使用butil::IOBufBuilder,它的用法和std::ostringstream是一样的。对于有大量对象要打印的场景,IOBufBuilder简化了代码,效率也可能比c-style printf更高。

  1. brpc::Controller cntl;
  2. cntl.http_request().uri() = "..."; // 设置为待访问的URL
  3. cntl.http_request().set_method(brpc::HTTP_METHOD_POST);
  4. butil::IOBufBuilder os;
  5. os << "A lot of printing" << printable_objects << ...;
  6. os.move_to(cntl.request_attachment());
  7. channel.CallMethod(NULL, &cntl, NULL, NULL, NULL/*done*/);

控制HTTP版本

brpc的http行为默认是http/1.1。

http/1.0相比http/1.1缺少长连接功能,brpc client与一些古老的http server通信时可能需要按如下方法设置为1.0。

  1. cntl.http_request().set_version(1, 0);

设置http版本对h2无效,但是client收到的h2 response和server收到的h2 request中的version会被设置为(2, 0)。

brpc server会自动识别HTTP版本,并相应回复,无需用户设置。

URL

URL的一般形式如下图:

  1. // URI scheme : http://en.wikipedia.org/wiki/URI_scheme
  2. //
  3. // foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose
  4. // \_/ \_______________/ \_________/ \__/ \___/ \_/ \______________________/ \__/
  5. // | | | | | | | |
  6. // | userinfo host port | | query fragment
  7. // | \________________________________/\_____________|____|/ \__/ \__/
  8. // scheme | | | | | |
  9. // authority | | | | |
  10. // path | | interpretable as keys
  11. // | |
  12. // \_______________________________________________|____|/ \____/ \_____/
  13. // | | | | |
  14. // hierarchical part | | interpretable as values
  15. // | |
  16. // interpretable as filename |
  17. // |
  18. // |
  19. // interpretable as extension

在上面例子中可以看到,Channel.Init()和cntl.http_request().uri()被设置了相同的URL。为什么Channel为什么不直接利用Init时传入的URL,而需要给uri()再设置一次?

确实,在简单使用场景下,这两者有所重复,但在复杂场景中,两者差别很大,比如:

  • 访问命名服务(如BNS)下的多个http/h2 server。此时Channel.Init传入的是对该命名服务有意义的名称(如BNS中的节点名称),对uri()的赋值则是包含Host的完整URL(比如”www.foo.com/index.html?name=value”)。
  • 通过http/h2 proxy访问目标server。此时Channel.Init传入的是proxy server的地址,但uri()填入的是目标server的URL。

Host字段

若用户自己填写了”host”字段(大小写不敏感),框架不会修改。

若用户没有填且URL中包含host,比如http://www.foo.com/path,则http request中会包含”Host: www.foo.com“。

若用户没有填且URL不包含host,比如”/index.html?name=value”,但如果Channel初始化的地址包含域名,则框架会以域名作为Host,比如”http://www.foo.com",该http server将会看到”Host: www.foo.com“。如果地址是”http://www.foo.com:8989",则该http server将会看到”Host: www.foo.com:8989”。

若用户没有填且URL不包含host,比如”/index.html?name=value”,如果Channel初始化的地址也不包含域名,则框架会以目标server的ip和port为Host,地址为10.46.188.39:8989的http server将会看到”Host: 10.46.188.39:8989”。

对应的字段在h2中叫”:authority”。

常见设置

以http request为例 (对response的操作自行替换), 常见操作方式如下所示:

访问名为Foo的header

  1. const std::string* value = cntl->http_request().GetHeader("Foo"); //不存在为NULL

设置名为Foo的header

  1. cntl->http_request().SetHeader("Foo", "value");

访问名为Foo的query

  1. const std::string* value = cntl->http_request().uri().GetQuery("Foo"); // 不存在为NULL

设置名为Foo的query

  1. cntl->http_request().uri().SetQuery("Foo", "value");

设置HTTP Method

  1. cntl->http_request().set_method(brpc::HTTP_METHOD_POST);

设置url

  1. cntl->http_request().uri() = "http://www.baidu.com";

设置content-type

  1. cntl->http_request().set_content_type("text/plain");

访问body

  1. butil::IOBuf& buf = cntl->request_attachment();
  2. std::string str = cntl->request_attachment().to_string(); // 有拷贝

设置body

  1. cntl->request_attachment().append("....");
  2. butil::IOBufBuilder os;
  3. os << "....";
  4. os.move_to(cntl->request_attachment());

Notes on http header:

  • 根据rfc2616,http header的field_name不区分大小写。brpc支持大小写不敏感,同时会在打印时保持用户传入的大小写。
  • 若http header中出现了相同的field_name, 根据rfc2616,value应合并到一起,用逗号(,)分隔,用户自行处理.
  • query之间用”&“分隔, key和value之间用”=“分隔, value可以省略,比如key1=value1&key2&key3=value3中key2是合理的query,值为空字符串。

查看HTTP消息

打开-http_verbose即可看到所有的http/h2 request和response,注意这应该只用于线下调试,而不是线上程序。

HTTP错误

当Server返回的http status code不是2xx时,该次http/h2访问被视为失败,client端会把cntl->ErrorCode()设置为EHTTP,用户可通过cntl->http_response().status_code()获得具体的http错误。同时server端可以把代表错误的html或json置入cntl->response_attachment()作为http body传递回来。

压缩request body

调用Controller::set_request_compress_type(brpc::COMPRESS_TYPE_GZIP)将尝试用gzip压缩http body。

“尝试”指的是压缩有可能不发生,条件有:

  • body尺寸小于-http_body_compress_threshold指定的字节数,默认是512。这是因为gzip并不是一个很快的压缩算法,当body较小时,压缩增加的延时可能比网络传输省下的还多。

解压response body

出于通用性考虑brpc不会自动解压response body,解压代码并不复杂,用户可以自己做,方法如下:

  1. #include <brpc/policy/gzip_compress.h>
  2. ...
  3. const std::string* encoding = cntl->http_response().GetHeader("Content-Encoding");
  4. if (encoding != NULL && *encoding == "gzip") {
  5. butil::IOBuf uncompressed;
  6. if (!brpc::policy::GzipDecompress(cntl->response_attachment(), &uncompressed)) {
  7. LOG(ERROR) << "Fail to un-gzip response body";
  8. return;
  9. }
  10. cntl->response_attachment().swap(uncompressed);
  11. }
  12. // cntl->response_attachment()中已经是解压后的数据了

持续下载

http client往往需要等待到body下载完整才结束RPC,这个过程中body都会存在内存中,如果body超长或无限长(比如直播用的flv文件),那么内存会持续增长,直到超时。这样的http client不适合下载大文件。

brpc client支持在读取完body前就结束RPC,让用户在RPC结束后再读取持续增长的body。注意这个功能不等同于“支持http chunked mode”,brpc的http实现一直支持解析chunked mode,这里的问题是如何让用户处理超长或无限长的body,和body是否以chunked mode传输无关。

使用方法如下:

  1. 首先实现ProgressiveReader,接口如下:

    1. #include <brpc/progressive_reader.h>
    2. ...
    3. class ProgressiveReader {
    4. public:
    5. // Called when one part was read.
    6. // Error returned is treated as *permenant* and the socket where the
    7. // data was read will be closed.
    8. // A temporary error may be handled by blocking this function, which
    9. // may block the HTTP parsing on the socket.
    10. virtual butil::Status OnReadOnePart(const void* data, size_t length) = 0;
    11. // Called when there's nothing to read anymore. The `status' is a hint for
    12. // why this method is called.
    13. // - status.ok(): the message is complete and successfully consumed.
    14. // - otherwise: socket was broken or OnReadOnePart() failed.
    15. // This method will be called once and only once. No other methods will
    16. // be called after. User can release the memory of this object inside.
    17. virtual void OnEndOfMessage(const butil::Status& status) = 0;
    18. };

    OnReadOnePart在每读到一段数据时被调用,OnEndOfMessage在数据结束或连接断开时调用,实现前仔细阅读注释。

  2. 发起RPC前设置cntl.response_will_be_read_progressively(); 这告诉brpc在读取http response时只要读完header部分RPC就可以结束了。

  3. RPC结束后调用cntl.ReadProgressiveAttachmentBy(new MyProgressiveReader); MyProgressiveReader就是用户实现ProgressiveReader的实例。用户可以在这个实例的OnEndOfMessage接口中删除这个实例。

持续上传

目前Post的数据必须是完整生成好的,不适合POST超长的body。

访问带认证的Server

根据Server的认证方式生成对应的auth_data,并设置为http header “Authorization”的值。比如用的是curl,那就加上选项-H "Authorization : <auth_data>"。

发送https请求

https是http over SSL的简称,SSL并不是http特有的,而是对所有协议都有效。开启客户端SSL的一般性方法见这里。为方便使用,brpc会对https开头的uri自动开启SSL。


修改于 2023年5月16日: add security bug fix pages (#148) (a29da9f)