diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpRequestFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpRequestFeature.cs index 4b52060177..16511caa74 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpRequestFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpRequestFeature.cs @@ -5,15 +5,62 @@ using System.IO; namespace Microsoft.AspNetCore.Http.Features { + /// + /// Contains the details of a given request. These properties should all be mutable. + /// None of these properties should ever be set to null. + /// public interface IHttpRequestFeature { + /// + /// The HTTP-version as defined in RFC 7230. E.g. "HTTP/1.1" + /// string Protocol { get; set; } + + /// + /// The request uri scheme. E.g. "http" or "https". Note this value is not included + /// in the original request, it is inferred by checking if the transport used a TLS + /// connection or not. + /// string Scheme { get; set; } + + /// + /// The request method as defined in RFC 7230. E.g. "GET", "HEAD", "POST", etc.. + /// string Method { get; set; } + + /// + /// The first portion of the request path associated with application root. The value + /// is un-escaped. The value may be string.Empty. + /// string PathBase { get; set; } + + /// + /// The portion of the request path that identifies the requested resource. The value + /// is un-escaped. The value may be string.Empty if contains the + /// full path. + /// string Path { get; set; } + + /// + /// The query portion of the request-target as defined in RFC 7230. The value + /// may be string.Empty. If not empty then the leading '?' will be included. The value + /// is in its original form, without un-escaping. + /// string QueryString { get; set; } + + /// + /// Headers included in the request, aggregated by header name. The values are not split + /// or merged across header lines. E.g. The following headers: + /// HeaderA: value1, value2 + /// HeaderA: value3 + /// Result in Headers["HeaderA"] = { "value1, value2", "value3" } + /// IHeaderDictionary Headers { get; set; } + + /// + /// A representing the request body, if any. Stream.Null may be used + /// to represent an empty request body. + /// Stream Body { get; set; } } } diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpRequestLifetimeFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpRequestLifetimeFeature.cs index 3a93c3d1e5..1bdac15766 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpRequestLifetimeFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpRequestLifetimeFeature.cs @@ -7,7 +7,17 @@ namespace Microsoft.AspNetCore.Http.Features { public interface IHttpRequestLifetimeFeature { + /// + /// A that fires if the request is aborted and + /// the application should cease processing. The token will not fire if the request + /// completes successfully. + /// CancellationToken RequestAborted { get; set; } + + /// + /// Forcefully aborts the request if it has not already completed. This will result in + /// RequestAborted being triggered. + /// void Abort(); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpResponseFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpResponseFeature.cs index 8ea43d61fd..9d3b957efb 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpResponseFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpResponseFeature.cs @@ -7,14 +7,53 @@ using System.Threading.Tasks; namespace Microsoft.AspNetCore.Http.Features { + /// + /// Represents the fields and state of an HTTP response. + /// public interface IHttpResponseFeature { + /// + /// The status-code as defined in RFC 7230. The default value is 200. + /// int StatusCode { get; set; } + + /// + /// The reason-phrase as defined in RFC 7230. Note this field is no longer supported by HTTP/2. + /// string ReasonPhrase { get; set; } + + /// + /// The response headers to send. Headers with multiple values will be emitted as multiple headers. + /// IHeaderDictionary Headers { get; set; } + + /// + /// The for writing the response body. + /// Stream Body { get; set; } + + /// + /// Indicates if the response has started. If true, the , + /// , and are now immutable, and + /// OnStarting should no longer be called. + /// bool HasStarted { get; } + + /// + /// Registers a callback to be invoked just before the response starts. This is the + /// last chance to modify the , , or + /// . + /// + /// The callback to invoke when starting the response. + /// The state to pass into the callback. void OnStarting(Func callback, object state); + + /// + /// Registers a callback to be invoked after a response has fully completed. This is + /// intended for resource cleanup. + /// + /// The callback to invoke after the response has completed. + /// The state to pass into the callback. void OnCompleted(Func callback, object state); } } diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpSendFileFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpSendFileFeature.cs index 9418a7ffbe..1e2684130f 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpSendFileFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpSendFileFeature.cs @@ -1,13 +1,26 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. +using System.IO; using System.Threading; using System.Threading.Tasks; namespace Microsoft.AspNetCore.Http.Features { + /// + /// Provides an efficient mechanism for transferring files from disk to the network. + /// public interface IHttpSendFileFeature { + /// + /// Sends the requested file in the response body. This may bypass the IHttpResponseFeature.Body + /// . A response may include multiple writes. + /// + /// The full disk path to the file. + /// The offset in the file to start at. + /// The number of bytes to send, or null to send the remainder of the file. + /// A used to abort the transmission. + /// Task SendFileAsync(string path, long offset, long? count, CancellationToken cancellation); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpUpgradeFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpUpgradeFeature.cs index e98065bc4d..e434fe0b97 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpUpgradeFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpUpgradeFeature.cs @@ -8,7 +8,17 @@ namespace Microsoft.AspNetCore.Http.Features { public interface IHttpUpgradeFeature { + /// + /// Indicates if the server can upgrade this request to an opaque, bidirectional stream. + /// bool IsUpgradableRequest { get; } + + /// + /// Attempt to upgrade the request to an opaque, bidirectional stream. The response status code + /// and headers need to be set before this is invoked. Check + /// before invoking. + /// + /// Task UpgradeAsync(); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.Http.Features/IHttpWebSocketFeature.cs b/src/Microsoft.AspNetCore.Http.Features/IHttpWebSocketFeature.cs index 49b28bc38f..c1d116126a 100644 --- a/src/Microsoft.AspNetCore.Http.Features/IHttpWebSocketFeature.cs +++ b/src/Microsoft.AspNetCore.Http.Features/IHttpWebSocketFeature.cs @@ -8,8 +8,17 @@ namespace Microsoft.AspNetCore.Http.Features { public interface IHttpWebSocketFeature { + /// + /// Indicates if this is a WebSocket upgrade request. + /// bool IsWebSocketRequest { get; } + /// + /// Attempts to upgrade the request to a . Check + /// before invoking this. + /// + /// + /// Task AcceptAsync(WebSocketAcceptContext context); } } \ No newline at end of file diff --git a/src/Microsoft.AspNetCore.Http.Features/ISession.cs b/src/Microsoft.AspNetCore.Http.Features/ISession.cs index 0904703d39..74b63baa62 100644 --- a/src/Microsoft.AspNetCore.Http.Features/ISession.cs +++ b/src/Microsoft.AspNetCore.Http.Features/ISession.cs @@ -8,20 +8,55 @@ namespace Microsoft.AspNetCore.Http { public interface ISession { + /// + /// A unique identifier for the current session. This is not the same as the session cookie + /// since the cookie lifetime may not be the same as the session entry lifetime in the data store. + /// string Id { get; } + /// + /// Enumerates all the keys, if any. + /// IEnumerable Keys { get; } + /// + /// Load the session from the data store. This may throw if the data store is unavailable. + /// + /// Task LoadAsync(); + /// + /// Store the session in the data store. This may throw if the data store is unavailable. + /// + /// Task CommitAsync(); + /// + /// Retrieve the value of the given key, if present. + /// + /// + /// + /// bool TryGetValue(string key, out byte[] value); + /// + /// Set the given key and value in the current session. This will throw if the session + /// was not established prior to sending the response. + /// + /// + /// void Set(string key, byte[] value); + /// + /// Remove the given key from the session if present. + /// + /// void Remove(string key); + /// + /// Remove all entries from the current session, if any. + /// The session cookie is not removed. + /// void Clear(); } } \ No newline at end of file