http_service.md 19.6 KB
Newer Older
gejun's avatar
gejun committed
1
[中文版](../cn/http_service.md)
2

Ge Jun's avatar
Ge Jun committed
3 4 5 6 7 8 9 10 11 12 13 14
This document talks about ordinary htt/h2 services rather than protobuf services accessible via http/h2. 
http/h2 services in brpc have to declare interfaces with empty request and response in a .proto file. This requirement keeps all service declarations inside proto files rather than scattering in code, configurations, and proto files.

# Example

[http_server.cpp](https://github.com/brpc/brpc/blob/master/example/http_c++/http_server.cpp)

# About h2

brpc names the HTTP/2 protocol to "h2", no matter encrypted or not. However HTTP/2 connections without SSL are shown on /connections with the official name "h2c", and the ones with SSL are shown as "h2".

The APIs for http and h2 in brpc are basically same. Without explicit statement, mentioned http features work for h2 as well.
15

gejun's avatar
gejun committed
16
# URL types
17

gejun's avatar
gejun committed
18
## /ServiceName/MethodName as the prefix
19

Ge Jun's avatar
Ge Jun committed
20
Define a service named `ServiceName`(not including the package name), with a method named `MethodName` and empty request/response, the service will provide http/h2 service on `/ServiceName/MethodName` by default.
gejun's avatar
gejun committed
21

Ge Jun's avatar
Ge Jun committed
22
The reason that request and response can be empty is that all data are in Controller:
gejun's avatar
gejun committed
23

Ge Jun's avatar
Ge Jun committed
24 25
- Header of the http/h2 request is in Controller.http_request() and the body is in Controller.request_attachment().
- Header of the http/h2 response is in Controller.http_response() and the body is in Controller.response_attachment().
gejun's avatar
gejun committed
26 27 28 29

Implementation steps:

1. Add the service declaration in a proto file.
30 31 32 33 34 35 36 37 38 39 40 41

```protobuf
option cc_generic_services = true;
 
message HttpRequest { };
message HttpResponse { };
 
service HttpService {
      rpc Echo(HttpRequest) returns (HttpResponse);
};
```

gejun's avatar
gejun committed
42
2. Implement the service by inheriting the base class generated in .pb.h, which is same as protobuf services.
43 44 45 46 47 48 49 50 51 52 53 54

```c++
class HttpServiceImpl : public HttpService {
public:
    ...
    virtual void Echo(google::protobuf::RpcController* cntl_base,
                      const HttpRequest* /*request*/,
                      HttpResponse* /*response*/,
                      google::protobuf::Closure* done) {
        brpc::ClosureGuard done_guard(done);
        brpc::Controller* cntl = static_cast<brpc::Controller*>(cntl_base);
 
gejun's avatar
gejun committed
55
        // body is plain text
56 57
        cntl->http_response().set_content_type("text/plain");
       
gejun's avatar
gejun committed
58
        // Use printed query string and body as the response.
59 60 61 62 63 64 65 66 67 68 69 70
        butil::IOBufBuilder os;
        os << "queries:";
        for (brpc::URI::QueryIterator it = cntl->http_request().uri().QueryBegin();
                it != cntl->http_request().uri().QueryEnd(); ++it) {
            os << ' ' << it->first << '=' << it->second;
        }
        os << "\nbody: " << cntl->request_attachment() << '\n';
        os.move_to(cntl->response_attachment());
    }
};
```

gejun's avatar
gejun committed
71
3. After adding the implemented instance into the server, the service is accessible via following URLs (Note that the path after `/HttpService/Echo ` is filled into `cntl->http_request().unresolved_path()`, which is always normalized):
72 73 74 75 76 77 78 79 80

| URL                        | Protobuf Method  | cntl->http_request().uri().path() | cntl->http_request().unresolved_path() |
| -------------------------- | ---------------- | --------------------------------- | -------------------------------------- |
| /HttpService/Echo          | HttpService.Echo | "/HttpService/Echo"               | ""                                     |
| /HttpService/Echo/Foo      | HttpService.Echo | "/HttpService/Echo/Foo"           | "Foo"                                  |
| /HttpService/Echo/Foo/Bar  | HttpService.Echo | "/HttpService/Echo/Foo/Bar"       | "Foo/Bar"                              |
| /HttpService//Echo///Foo// | HttpService.Echo | "/HttpService//Echo///Foo//"      | "Foo"                                  |
| /HttpService               | No such method   |                                   |                                        |

gejun's avatar
gejun committed
81
## /ServiceName as the prefix
82

Ge Jun's avatar
Ge Jun committed
83
http/h2 services for managing resources may need this kind of URL, such as `/FileService/foobar.txt` represents `./foobar.txt` and `/FileService/app/data/boot.cfg` represents `./app/data/boot.cfg`.
84

gejun's avatar
gejun committed
85
Implementation steps:
86

gejun's avatar
gejun committed
87
1. Use `FileService` as the service name and `default_method` as the method name in the proto file.
88 89 90

```protobuf
option cc_generic_services = true;
gejun's avatar
gejun committed
91

92 93
message HttpRequest { };
message HttpResponse { };
gejun's avatar
gejun committed
94

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
service FileService {
      rpc default_method(HttpRequest) returns (HttpResponse);
}
```

2. Implement the service.

```c++
class FileServiceImpl: public FileService {
public:
    ...
    virtual void default_method(google::protobuf::RpcController* cntl_base,
                                const HttpRequest* /*request*/,
                                HttpResponse* /*response*/,
                                google::protobuf::Closure* done) {
        brpc::ClosureGuard done_guard(done);
        brpc::Controller* cntl = static_cast<brpc::Controller*>(cntl_base);
        cntl->response_attachment().append("Getting file: ");
        cntl->response_attachment().append(cntl->http_request().unresolved_path());
    }
};
```

gejun's avatar
gejun committed
118
3. After adding the implemented instance into the server, the service is accessible via following URLs (the path after `/FileService` is filled in `cntl->http_request().unresolved_path()`, which is always normalized):
119 120 121 122 123 124 125 126

| URL                             | Protobuf Method            | cntl->http_request().uri().path() | cntl->http_request().unresolved_path() |
| ------------------------------- | -------------------------- | --------------------------------- | -------------------------------------- |
| /FileService                    | FileService.default_method | "/FileService"                    | ""                                     |
| /FileService/123.txt            | FileService.default_method | "/FileService/123.txt"            | "123.txt"                              |
| /FileService/mydir/123.txt      | FileService.default_method | "/FileService/mydir/123.txt"      | "mydir/123.txt"                        |
| /FileService//mydir///123.txt// | FileService.default_method | "/FileService//mydir///123.txt//" | "mydir/123.txt"                        |

gejun's avatar
gejun committed
127
## Restful URL
128

gejun's avatar
gejun committed
129
brpc supports specifying a URL for each method in a service. The API is as follows:
130 131 132

```c++
// If `restful_mappings' is non-empty, the method in service can
gejun's avatar
gejun committed
133
// be accessed by the specified URL rather than /ServiceName/MethodName.
134
// Mapping rules: "PATH1 => NAME1, PATH2 => NAME2 ..."
Ge Jun's avatar
Ge Jun committed
135
// where `PATH' is a valid path and `NAME' is the method name.
136 137 138 139 140
int AddService(google::protobuf::Service* service,
               ServiceOwnership ownership,
               butil::StringPiece restful_mappings);
```

Ge Jun's avatar
Ge Jun committed
141
`QueueService` defined below contains several methods. If the service is added into the server normally, it's accessible via URLs like `/QueueService/start` and ` /QueueService/stop`.
142 143 144 145 146 147 148 149 150 151

```protobuf
service QueueService {
    rpc start(HttpRequest) returns (HttpResponse);
    rpc stop(HttpRequest) returns (HttpResponse);
    rpc get_stats(HttpRequest) returns (HttpResponse);
    rpc download_data(HttpRequest) returns (HttpResponse);
};
```

gejun's avatar
gejun committed
152
By specifying the 3rd parameter `restful_mappings` to `AddService`, the URL can be customized:
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173

```c++
if (server.AddService(&queue_svc,
                      brpc::SERVER_DOESNT_OWN_SERVICE,
                      "/v1/queue/start   => start,"
                      "/v1/queue/stop    => stop,"
                      "/v1/queue/stats/* => get_stats") != 0) {
    LOG(ERROR) << "Fail to add queue_svc";
    return -1;
}
 
if (server.AddService(&queue_svc,
                      brpc::SERVER_DOESNT_OWN_SERVICE,
                      "/v1/*/start   => start,"
                      "/v1/*/stop    => stop,"
                      "*.data        => download_data") != 0) {
    LOG(ERROR) << "Fail to add queue_svc";
    return -1;
}
```

gejun's avatar
gejun committed
174
There are 3 mappings separated by comma in the 3rd parameter (which is a string spanning 3 lines) to the `AddService`. Each mapping tells brpc to call the method at right side of the arrow if the left side matches the URL. The asterisk in `/v1/queue/stats/*` matches any string.
175

gejun's avatar
gejun committed
176
More about mapping rules:
177

gejun's avatar
gejun committed
178
- Multiple paths can be mapped to a same method.
Ge Jun's avatar
Ge Jun committed
179
- Both http/h2 and protobuf services are supported.
gejun's avatar
gejun committed
180 181 182 183 184
- Un-mapped methods are still accessible via `/ServiceName/MethodName`. Mapped methods are **not** accessible via `/ServiceName/MethodName` anymore.
- `==>` and ` ===>` are both OK, namely extra spaces at the beginning or the end, extra slashes, extra commas at the end, are all accepted.
- Pattern `PATH` and `PATH/*` can coexist.
- Support suffix matching: characters can appear after the asterisk.
- At most one asterisk is allowed in a path.
185

gejun's avatar
gejun committed
186
The path after asterisk can be obtained by `cntl.http_request().unresolved_path()`, which is always normalized, namely no slashes at the beginning or the end, and no repeated slashes in the middle. For example:
187 188 189 190 191 192 193

![img](../images/restful_1.png)

or:

![img](../images/restful_2.png)

gejun's avatar
gejun committed
194
in which unresolved_path are both `foo/bar`. The extra slashes at the left, the right, or the middle are removed.
195 196 197

Note that `cntl.http_request().uri().path()` is not ensured to be normalized, which is `"//v1//queue//stats//foo///bar//////"` and `"//vars///foo////bar/////"` respectively in the above example.

gejun's avatar
gejun committed
198
The built-in service page of `/status` shows customized URLs after the methods, in form of `@URL1 @URL2` ...
199 200 201 202 203 204 205

![img](../images/restful_3.png)

# HTTP Parameters

## HTTP headers

gejun's avatar
gejun committed
206 207 208
HTTP headers are a series of key/value pairs, some of them are defined by the HTTP specification, while others are free to use.

Query strings are also key/value pairs. Differences between HTTP headers and query strings:
209

gejun's avatar
gejun committed
210 211
* Although operations on HTTP headers are accurately defined by the http specification, but http headers cannot be modified directly from an address bar, they are often used for passing parameters of a protocol or framework.
* Query strings is part of the URL and **often** in form of `key1=value1&key2=value2&...`, which is easy to read and modify. They're often used for passing application-level parameters. However format of query strings is not defined in HTTP spec, just a convention.
212 213 214 215 216 217 218 219 220 221 222 223 224

```c++
// Get value for header "User-Agent" (case insensitive)
const std::string* user_agent_str = cntl->http_request().GetHeader("User-Agent");
if (user_agent_str != NULL) {  // has the header
    LOG(TRACE) << "User-Agent is " << *user_agent_str;
}
...
 
// Add a header "Accept-encoding: gzip" (case insensitive)
cntl->http_response().SetHeader("Accept-encoding", "gzip");
// Overwrite the previous header "Accept-encoding: deflate"
cntl->http_response().SetHeader("Accept-encoding", "deflate");
gejun's avatar
gejun committed
225
// Append value to the previous header so that it becomes
226 227 228 229 230 231
// "Accept-encoding: deflate,gzip" (values separated by comma)
cntl->http_response().AppendHeader("Accept-encoding", "gzip");
```

## Content-Type

gejun's avatar
gejun committed
232
`Content-type` is a frequently used header for storing type of the HTTP body, and specially processed in brpc and accessible by `cntl->http_request().content_type()` . As a correspondence, `cntl->GetHeader("Content-Type")` returns nothing.
233 234 235 236 237 238 239 240 241 242 243

```c++
// Get Content-Type
if (cntl->http_request().content_type() == "application/json") {
    ...
}
...
// Set Content-Type
cntl->http_response().set_content_type("text/html");
```

gejun's avatar
gejun committed
244
If the RPC fails (`Controller` has been `SetFailed`), the framework overwrites `Content-Type` with `text/plain` and sets the response body with `Controller::ErrorText()`.
245 246 247

## Status Code

gejun's avatar
gejun committed
248
Status code is a special field in HTTP response to store processing result of the http request. Possible values are defined in [http_status_code.h](https://github.com/brpc/brpc/blob/master/src/brpc/http_status_code.h).
249 250 251 252 253 254 255 256 257 258 259 260

```c++
// Get Status Code
if (cntl->http_response().status_code() == brpc::HTTP_STATUS_NOT_FOUND) {
    LOG(FATAL) << "FAILED: " << controller.http_response().reason_phrase();
}
...
// Set Status code
cntl->http_response().set_status_code(brpc::HTTP_STATUS_INTERNAL_SERVER_ERROR);
cntl->http_response().set_status_code(brpc::HTTP_STATUS_INTERNAL_SERVER_ERROR, "My explanation of the error...");
```

gejun's avatar
gejun committed
261
For example, following code implements redirection with status code 302:
262 263 264 265 266 267 268 269 270 271

```c++
cntl->http_response().set_status_code(brpc::HTTP_STATUS_FOUND);
cntl->http_response().SetHeader("Location", "http://bj.bs.bae.baidu.com/family/image001(4979).jpg");
```

![img](../images/302.png)

## Query String

gejun's avatar
gejun committed
272
As mentioned in above [HTTP headers](#http-headers), query strings are interpreted in common convention, whose form is `key1=value1&key2=value2&…`. Keys without values are acceptable as well and accessible by `GetQuery` which returns an empty string. Such keys are often used as boolean flags. Full API are defined in [uri.h](https://github.com/brpc/brpc/blob/master/src/brpc/uri.h).
273 274 275 276 277 278

```c++
const std::string* time_value = cntl->http_request().uri().GetQuery("time");
if (time_value != NULL) {  // the query string is present
    LOG(TRACE) << "time = " << *time_value;
}
gejun's avatar
gejun committed
279

280 281 282 283
...
cntl->http_request().uri().SetQuery("time", "2015/1/2");
```

gejun's avatar
gejun committed
284
# Debugging
285

286
Turn on [-http_verbose](http://brpc.baidu.com:8765/flags/http_verbose) to print contents of all http requests and responses. Note that this should only be used for debugging rather than online services.
287

gejun's avatar
gejun committed
288 289 290 291 292
# Compress the response body

HTTP services often compress http bodies to reduce transmission latency of web pages and speed up the presentations to end users.

Call `Controller::set_response_compress_type(brpc::COMPRESS_TYPE_GZIP)` to **try to** compress the http body with gzip. "Try to" means the compression may not happen in following conditions:
293

gejun's avatar
gejun committed
294
* The request does not set `Accept-encoding` or the value does not contain "gzip". For example, curl does not support compression without option `--compressed`, in which case the server always returns uncompressed results.
295

gejun's avatar
gejun committed
296
* Body size is less than the bytes specified by -http_body_compress_threshold (512 by default). gzip is not a very fast compression algorithm. When the body is small, the delay added by compression may be larger than the time saved by network transmission. No compression when the body is relatively small is probably a better choice.
297

gejun's avatar
gejun committed
298 299 300
  | Name                         | Value | Description                              | Defined At                            |
  | ---------------------------- | ----- | ---------------------------------------- | ------------------------------------- |
  | http_body_compress_threshold | 512   | Not compress http body when it's less than so many bytes. | src/brpc/policy/http_rpc_protocol.cpp |
301

gejun's avatar
gejun committed
302 303 304
# Decompress the request body

Due to generality, brpc does not decompress request bodies automatically, but users can do the job by themselves as follows:
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320

```c++
#include <brpc/policy/gzip_compress.h>
...
const std::string* encoding = cntl->http_request().GetHeader("Content-Encoding");
if (encoding != NULL && *encoding == "gzip") {
    butil::IOBuf uncompressed;
    if (!brpc::policy::GzipDecompress(cntl->request_attachment(), &uncompressed)) {
        LOG(ERROR) << "Fail to un-gzip request body";
        return;
    }
    cntl->request_attachment().swap(uncompressed);
}
// cntl->request_attachment() contains the data after decompression
```

gejun's avatar
gejun committed
321 322 323
# Serve https requests
https is short for "http over SSL", SSL is not exclusive for http, but effective for all protocols. The generic method for turning on server-side SSL is [here](server.md#turn-on-ssl).

324 325
# Performance

gejun's avatar
gejun committed
326
Productions without extreme performance requirements tend to use HTTP protocol, especially mobile products. Thus we put great emphasis on implementation qualities of HTTP. To be more specific:
327

gejun's avatar
gejun committed
328 329 330 331
- Use [http parser](https://github.com/brpc/brpc/blob/master/src/brpc/details/http_parser.h) of node.js to parse http messages, which is a lightweight, well-written, and extensively used implementation.
- Use [rapidjson](https://github.com/miloyip/rapidjson) to parse json, which is a json library focuses on performance.
- In the worst case, the time complexity of parsing http requests is still O(N), where N is byte size of the request. As a contrast, parsing code that requires the http request to be complete, may cost O(N^2) time in the worst case. This feature is very helpful since many HTTP requests are large.
- Processing HTTP messages from different clients is highly concurrent, even a pretty complicated http message does not block responding other clients. It's difficult to achieve this for other RPC implementations and http servers often based on [single-threaded reactor](threading_overview.md#single-threaded-reactor).
332 333 334

# Progressive sending

gejun's avatar
gejun committed
335 336 337 338 339 340 341 342 343 344
brpc server is capable of sending large or infinite sized body, in following steps:

1. Call `Controller::CreateProgressiveAttachment()` to create a body that can be written progressively. The returned `ProgressiveAttachment` object should be managed by `intrusive_ptr`
  ```c++
  #include <brpc/progressive_attachment.h>
  ...
  butil::intrusive_ptr<brpc::ProgressiveAttachment> pa (cntl->CreateProgressiveAttachment());
  ```

2. Call `ProgressiveAttachment::Write()` to send the data.
345

gejun's avatar
gejun committed
346 347 348 349
   * If the write occurs before running of the server-side done, the sent data is cached until the done is called.
   * If the write occurs after running of the server-side done, the sent data is written out in chunked mode immediately.

3. After usage, destruct all `butil::intrusive_ptr<brpc::ProgressiveAttachment>` to release related resources.
350 351 352

# Progressive receiving

gejun's avatar
gejun committed
353
Currently brpc server doesn't support calling the service callback once header part in the http request is parsed. In other words, brpc server is not suitable for receiving large or infinite sized body.
354 355 356

# FAQ

gejun's avatar
gejun committed
357 358 359
### Q: The nginx before brpc encounters final fail

The error is caused by that brpc server closes the http connection directly without sending a response.
360

gejun's avatar
gejun committed
361
brpc server supports a variety of protocols on the same port. When a request is failed to be parsed in HTTP, it's hard to tell that the request is definitely in HTTP. If the request is very likely to be one, the server sends HTTP 400 errors and closes the connection. However, if the error is caused HTTP method(at the beginning) or ill-formed serialization (may be caused by bugs at the HTTP client), the server still closes the connection without sending a response, which leads to "final fail" at nginx.
362

gejun's avatar
gejun committed
363
Solution: When using Nginx to forward traffic, set `$HTTP_method` to allowed HTTP methods or simply specify the HTTP method in `proxy_method`.
364 365 366

### Q: Does brpc support http chunked mode

gejun's avatar
gejun committed
367
Yes.
368

gejun's avatar
gejun committed
369
### Q: Why do HTTP requests containing BASE64 encoded query string fail to parse sometimes?
370

gejun's avatar
gejun committed
371
According to the [HTTP specification](http://tools.ietf.org/html/rfc3986#section-2.2), following characters need to be encoded with `%`.
372 373 374 375 376 377 378 379 380 381

```
       reserved    = gen-delims / sub-delims

       gen-delims  = ":" / "/" / "?" / "#" / "[" / "]" / "@"

       sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
                   / "*" / "+" / "," / ";" / "="
```

gejun's avatar
gejun committed
382
Base64 encoded string may end with `=` which is a reserved character (take `?wi=NDgwMDB8dGVzdA==&anothorkey=anothervalue` as an example). The strings may be parsed successfully, or may be not, depending on the implementation which should not be assumed in principle.
383

gejun's avatar
gejun committed
384
One solution is to remove the trailing `=` which does not affect the [Base64 decoding](http://en.wikipedia.org/wiki/Base64#Padding). Another method is to [percent-encode](https://en.wikipedia.org/wiki/Percent-encoding) the URI, and do percent-decoding before Base64 decoding.