13c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller/* 23c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Copyright (C) 2011 The Android Open Source Project 33c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 43c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Licensed under the Apache License, Version 2.0 (the "License"); 53c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * you may not use this file except in compliance with the License. 63c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * You may obtain a copy of the License at 73c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 83c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * http://www.apache.org/licenses/LICENSE-2.0 93c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 103c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Unless required by applicable law or agreed to in writing, software 113c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * distributed under the License is distributed on an "AS IS" BASIS, 123c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 133c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * See the License for the specific language governing permissions and 143c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * limitations under the License. 153c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 163c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 1771b9f47b26fb57ac3e436a19519c6e3ec70e86ebNeil Fullerpackage com.squareup.okhttp.internal.framed; 183c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 193c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.io.Closeable; 203c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.io.IOException; 213c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.util.List; 223c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport okio.BufferedSource; 233c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport okio.ByteString; 243c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 253c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller/** Reads transport frames for SPDY/3 or HTTP/2. */ 263c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerpublic interface FrameReader extends Closeable { 27e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller void readConnectionPreface() throws IOException; 283c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller boolean nextFrame(Handler handler) throws IOException; 293c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 3071b9f47b26fb57ac3e436a19519c6e3ec70e86ebNeil Fuller interface Handler { 313c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void data(boolean inFinished, int streamId, BufferedSource source, int length) 323c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller throws IOException; 333c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 343c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 353c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Create or update incoming headers, creating the corresponding streams 363c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * if necessary. Frames that trigger this are SPDY SYN_STREAM, HEADERS, and 373c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * SYN_REPLY, and HTTP/2 HEADERS and PUSH_PROMISE. 383c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 393c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param outFinished true if the receiver should not send further frames. 403c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param inFinished true if the sender will not send further frames. 413c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param streamId the stream owning these headers. 423c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param associatedStreamId the stream that triggered the sender to create 43e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * this stream. 443c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 453c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId, 46e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller List<Header> headerBlock, HeadersMode headersMode); 473c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void rstStream(int streamId, ErrorCode errorCode); 483c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void settings(boolean clearPrevious, Settings settings); 493c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 503c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** HTTP/2 only. */ 513c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void ackSettings(); 523c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 533c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 543c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Read a connection-level ping from the peer. {@code ack} indicates this 553c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * is a reply. Payload parameters are different between SPDY/3 and HTTP/2. 563c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p> 573c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * In SPDY/3, only the first {@code payload1} parameter is set. If the 583c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * reader is a client, it is an unsigned even number. Likewise, a server 593c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * will receive an odd number. 603c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p> 613c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * In HTTP/2, both {@code payload1} and {@code payload2} parameters are 623c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * set. The data is opaque binary, and there are no rules on the content. 633c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 643c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void ping(boolean ack, int payload1, int payload2); 653c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 663c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 673c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * The peer tells us to stop creating streams. It is safe to replay 683c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * streams with {@code ID > lastGoodStreamId} on a new connection. In- 693c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * flight streams with {@code ID <= lastGoodStreamId} can only be replayed 703c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * on a new connection if they are idempotent. 713c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 723c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param lastGoodStreamId the last stream ID the peer processed before 733c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * sending this message. If {@code lastGoodStreamId} is zero, the peer 743c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * processed no frames. 753c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param errorCode reason for closing the connection. 76e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param debugData only valid for HTTP/2; opaque debug data to send. 773c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 783c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData); 793c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 803c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 813c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Notifies that an additional {@code windowSizeIncrement} bytes can be 823c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * sent on {@code streamId}, or the connection if {@code streamId} is zero. 833c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 843c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void windowUpdate(int streamId, long windowSizeIncrement); 85e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 86e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 87e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Called when reading a headers or priority frame. This may be used to 88e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * change the stream's weight from the default (16) to a new value. 89e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 90e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param streamId stream which has a priority change. 91e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param streamDependency the stream ID this stream is dependent on. 92e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param weight relative proportion of priority in [1..256]. 93e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param exclusive inserts this stream ID as the sole child of 94e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * {@code streamDependency}. 95e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 96e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller void priority(int streamId, int streamDependency, int weight, boolean exclusive); 973c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 983c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 993c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * HTTP/2 only. Receive a push promise header block. 1003c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p> 1013c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * A push promise contains all the headers that pertain to a server-initiated 1023c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * request, and a {@code promisedStreamId} to which response frames will be 1033c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * delivered. Push promise frames are sent as a part of the response to 104e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * {@code streamId}. 1053c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 1063c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param streamId client-initiated stream ID. Must be an odd number. 1073c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param promisedStreamId server-initiated stream ID. Must be an even 1083c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * number. 1093c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @param requestHeaders minimally includes {@code :method}, {@code :scheme}, 1103c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * {@code :authority}, and (@code :path}. 1113c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 1123c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller void pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders) 1133c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller throws IOException; 114e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 115e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 116e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * HTTP/2 only. Expresses that resources for the connection or a client- 117e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * initiated stream are available from a different network location or 118e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * protocol configuration. 119e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 120e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * <p>See <a href="http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-01">alt-svc</a> 121e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 122e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param streamId when a client-initiated stream ID (odd number), the 123e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * origin of this alternate service is the origin of the stream. When 124e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * zero, the origin is specified in the {@code origin} parameter. 125e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param origin when present, the 126e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * <a href="http://tools.ietf.org/html/rfc6454">origin</a> is typically 127e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * represented as a combination of scheme, host and port. When empty, 128e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * the origin is that of the {@code streamId}. 129e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param protocol an ALPN protocol, such as {@code h2}. 130e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param host an IP address or hostname. 131e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param port the IP port associated with the service. 132e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @param maxAge time in seconds that this alternative is considered fresh. 133e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 134e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller void alternateService(int streamId, String origin, ByteString protocol, String host, int port, 135e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller long maxAge); 1363c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller } 1373c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller} 138