1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.squareup.okhttp.internal.spdy;
18
19import java.io.Closeable;
20import java.io.IOException;
21import java.util.List;
22import okio.BufferedSource;
23import okio.ByteString;
24
25/** Reads transport frames for SPDY/3 or HTTP/2. */
26public interface FrameReader extends Closeable {
27  void readConnectionPreface() throws IOException;
28  boolean nextFrame(Handler handler) throws IOException;
29
30  public interface Handler {
31    void data(boolean inFinished, int streamId, BufferedSource source, int length)
32        throws IOException;
33
34    /**
35     * Create or update incoming headers, creating the corresponding streams
36     * if necessary. Frames that trigger this are SPDY SYN_STREAM, HEADERS, and
37     * SYN_REPLY, and HTTP/2 HEADERS and PUSH_PROMISE.
38     *
39     * @param outFinished true if the receiver should not send further frames.
40     * @param inFinished true if the sender will not send further frames.
41     * @param streamId the stream owning these headers.
42     * @param associatedStreamId the stream that triggered the sender to create
43     *     this stream.
44     */
45    void headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId,
46        List<Header> headerBlock, HeadersMode headersMode);
47    void rstStream(int streamId, ErrorCode errorCode);
48    void settings(boolean clearPrevious, Settings settings);
49
50    /** HTTP/2 only. */
51    void ackSettings();
52
53    /**
54     *  Read a connection-level ping from the peer.  {@code ack} indicates this
55     *  is a reply.  Payload parameters are different between SPDY/3 and HTTP/2.
56     *  <p>
57     *  In SPDY/3, only the first {@code payload1} parameter is set.  If the
58     *  reader is a client, it is an unsigned even number.  Likewise, a server
59     *  will receive an odd number.
60     *  <p>
61     *  In HTTP/2, both {@code payload1} and {@code payload2} parameters are
62     *  set. The data is opaque binary, and there are no rules on the content.
63     */
64    void ping(boolean ack, int payload1, int payload2);
65
66    /**
67     * The peer tells us to stop creating streams.  It is safe to replay
68     * streams with {@code ID > lastGoodStreamId} on a new connection.  In-
69     * flight streams with {@code ID <= lastGoodStreamId} can only be replayed
70     * on a new connection if they are idempotent.
71     *
72     * @param lastGoodStreamId the last stream ID the peer processed before
73     *     sending this message. If {@code lastGoodStreamId} is zero, the peer
74     *     processed no frames.
75     * @param errorCode reason for closing the connection.
76     * @param debugData only valid for HTTP/2; opaque debug data to send.
77     */
78    void goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData);
79
80    /**
81     * Notifies that an additional {@code windowSizeIncrement} bytes can be
82     * sent on {@code streamId}, or the connection if {@code streamId} is zero.
83     */
84    void windowUpdate(int streamId, long windowSizeIncrement);
85
86    /**
87     * Called when reading a headers or priority frame. This may be used to
88     * change the stream's weight from the default (16) to a new value.
89     *
90     * @param streamId stream which has a priority change.
91     * @param streamDependency the stream ID this stream is dependent on.
92     * @param weight relative proportion of priority in [1..256].
93     * @param exclusive inserts this stream ID as the sole child of
94     *     {@code streamDependency}.
95     */
96    void priority(int streamId, int streamDependency, int weight, boolean exclusive);
97
98    /**
99     * HTTP/2 only. Receive a push promise header block.
100     * <p>
101     * A push promise contains all the headers that pertain to a server-initiated
102     * request, and a {@code promisedStreamId} to which response frames will be
103     * delivered. Push promise frames are sent as a part of the response to
104     * {@code streamId}.
105     *
106     * @param streamId client-initiated stream ID.  Must be an odd number.
107     * @param promisedStreamId server-initiated stream ID.  Must be an even
108     * number.
109     * @param requestHeaders minimally includes {@code :method}, {@code :scheme},
110     * {@code :authority}, and (@code :path}.
111     */
112    void pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders)
113        throws IOException;
114
115    /**
116     * HTTP/2 only. Expresses that resources for the connection or a client-
117     * initiated stream are available from a different network location or
118     * protocol configuration.
119     *
120     * <p>See <a href="http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-01">alt-svc</a>
121     *
122     * @param streamId when a client-initiated stream ID (odd number), the
123     *     origin of this alternate service is the origin of the stream. When
124     *     zero, the origin is specified in the {@code origin} parameter.
125     * @param origin when present, the
126     *     <a href="http://tools.ietf.org/html/rfc6454">origin</a> is typically
127     *     represented as a combination of scheme, host and port. When empty,
128     *     the origin is that of the {@code streamId}.
129     * @param protocol an ALPN protocol, such as {@code h2}.
130     * @param host an IP address or hostname.
131     * @param port the IP port associated with the service.
132     * @param maxAge time in seconds that this alternative is considered fresh.
133     */
134    void alternateService(int streamId, String origin, ByteString protocol, String host, int port,
135        long maxAge);
136  }
137}
138