API.md

   1 ```
   2 /// HTTP Request NOT INCLUDING THE BODY. This allows for streaming
   3 public struct HTTPRequest {
   4     public var method : HTTPMethod
   5     public var target : String /* e.g. "/foo/bar?buz=qux" */
   6     public var httpVersion : HTTPVersion
   7     public var headers : HTTPHeaders
   8 }
   9
  10 /// Object that code writes the response and response body to.
  11 public protocol HTTPResponseWriter : class {
  12     func writeHeader(status: HTTPResponseStatus, headers: HTTPHeaders, completion: @escaping (Result) -> Void)
  13     func writeTrailer(_ trailers: HTTPHeaders, completion: @escaping (Result) -> Void)
  14     func writeBody(_ data: UnsafeHTTPResponseBody, completion: @escaping (Result) -> Void)
  15     func done(completion: @escaping (Result) -> Void)
  16     func abort()
  17 }
  18
  19 /// Convenience methods for HTTP response writer.
  20 extension HTTPResponseWriter {
  21     public func writeHeader(status: HTTPResponseStatus, headers: HTTPHeaders)
  22     public func writeHeader(status: HTTPResponseStatus)
  23     public func writeTrailer(_ trailers: HTTPHeaders)
  24     public func writeBody(_ data: UnsafeHTTPResponseBody)
  25     public func done()
  26 }
  27
  28 public protocol UnsafeHTTPResponseBody {
  29     func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
  30 }
  31
  32 extension UnsafeRawBufferPointer : UnsafeHTTPResponseBody {
  33     public func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
  34 }
  35
  36 public protocol HTTPResponseBody : UnsafeHTTPResponseBody {}
  37
  38 extension Data : HTTPResponseBody {
  39     public func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
  40 }
  41
  42 extension DispatchData : HTTPResponseBody {
  43     public func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
  44 }
  45
  46 extension String : HTTPResponseBody {
  47     public func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
  48 }
  49
  50 /// Method that takes a chunk of request body and is expected to write to the ResponseWriter
  51 public typealias HTTPBodyHandler = (HTTPBodyChunk, inout Bool) -> Void /* the Bool can be set to true when we don't want to process anything further */
  52
  53 /// Indicates whether the body is going to be processed or ignored
  54 public enum HTTPBodyProcessing {
  55     case discardBody /* if you're not interested in the body */
  56     case processBody(handler: HTTPBodyHandler)
  57 }
  58
  59 /// Part (or maybe all) of the incoming request body
  60 public enum HTTPBodyChunk {
  61     case chunk(data: DispatchData, finishedProcessing: () -> Void) /* a new bit of the HTTP request body has arrived, finishedProcessing() must be called when done with that chunk */
  62     case failed(error: /*HTTPParser*/ Error) /* error while streaming the HTTP request body, eg. connection closed */
  63     case trailer(key: String, value: String) /* trailer has arrived (this we actually haven't implemented yet) */
  64     case end /* body and trailers finished */
  65 }
  66
  67 /// Headers structure.
  68 public struct HTTPHeaders : Sequence, ExpressibleByDictionaryLiteral {
  69     public subscript(name: Name) -> String?
  70     public subscript(valuesFor name: Name) -> [String]
  71
  72     public struct Literal : ExpressibleByDictionaryLiteral { }
  73     public mutating func append(_ literal: HTTPHeaders.Literal)
  74     public mutating func replace(_ literal: HTTPHeaders.Literal)
  75
  76     public func makeIterator() -> AnyIterator<(name: Name, value: String)>
  77
  78     public struct Name : Hashable, ExpressibleByStringLiteral, CustomStringConvertible {
  79         public init(_ name: String)
  80
  81         // https://www.iana.org/assignments/message-headers/message-headers.xhtml
  82         // Permanent Message Header Field Names
  83         public static let aIM
  84         public static let accept
  85         public static let acceptAdditions
  86         public static let acceptCharset
  87         public static let acceptDatetime
  88         public static let acceptEncoding
  89         public static let acceptFeatures
  90         public static let acceptLanguage
  91         public static let acceptPatch
  92         public static let acceptPost
  93         public static let acceptRanges
  94         public static let age
  95         public static let allow
  96         public static let alpn
  97         public static let altSvc
  98         public static let altUsed
  99         public static let alternates
 100         public static let applyToRedirectRef
 101         public static let authenticationControl
 102         public static let authenticationInfo
 103         public static let authorization
 104         public static let cExt
 105         public static let cMan
 106         public static let cOpt
 107         public static let cPEP
 108         public static let cPEPInfo
 109         public static let cacheControl
 110         public static let calDAVTimezones
 111         public static let close
 112         public static let connection
 113         public static let contentBase
 114         public static let contentDisposition
 115         public static let contentEncoding
 116         public static let contentID
 117         public static let contentLanguage
 118         public static let contentLength
 119         public static let contentLocation
 120         public static let contentMD5
 121         public static let contentRange
 122         public static let contentScriptType
 123         public static let contentStyleType
 124         public static let contentType
 125         public static let contentVersion
 126         public static let cookie
 127         public static let cookie2
 128         public static let dasl
 129         public static let dav
 130         public static let date
 131         public static let defaultStyle
 132         public static let deltaBase
 133         public static let depth
 134         public static let derivedFrom
 135         public static let destination
 136         public static let differentialID
 137         public static let digest
 138         public static let eTag
 139         public static let expect
 140         public static let expires
 141         public static let ext
 142         public static let forwarded
 143         public static let from
 144         public static let getProfile
 145         public static let hobareg
 146         public static let host
 147         public static let http2Settings
 148         public static let im
 149         public static let `if`
 150         public static let ifMatch
 151         public static let ifModifiedSince
 152         public static let ifNoneMatch
 153         public static let ifRange
 154         public static let ifScheduleTagMatch
 155         public static let ifUnmodifiedSince
 156         public static let keepAlive
 157         public static let label
 158         public static let lastModified
 159         public static let link
 160         public static let location
 161         public static let lockToken
 162         public static let man
 163         public static let maxForwards
 164         public static let mementoDatetime
 165         public static let meter
 166         public static let mimeVersion
 167         public static let negotiate
 168         public static let opt
 169         public static let optionalWWWAuthenticate
 170         public static let orderingType
 171         public static let origin
 172         public static let overwrite
 173         public static let p3p
 174         public static let pep
 175         public static let picsLabel
 176         public static let pepInfo
 177         public static let position
 178         public static let pragma
 179         public static let prefer
 180         public static let preferenceApplied
 181         public static let profileObject
 182         public static let `protocol`
 183         public static let protocolInfo
 184         public static let protocolQuery
 185         public static let protocolRequest
 186         public static let proxyAuthenticate
 187         public static let proxyAuthenticationInfo
 188         public static let proxyAuthorization
 189         public static let proxyFeatures
 190         public static let proxyInstruction
 191         public static let `public`
 192         public static let publicKeyPins
 193         public static let publicKeyPinsReportOnly
 194         public static let range
 195         public static let redirectRef
 196         public static let referer
 197         public static let retryAfter
 198         public static let safe
 199         public static let scheduleReply
 200         public static let scheduleTag
 201         public static let secWebSocketAccept
 202         public static let secWebSocketExtensions
 203         public static let secWebSocketKey
 204         public static let secWebSocketProtocol
 205         public static let secWebSocketVersion
 206         public static let securityScheme
 207         public static let server
 208         public static let setCookie
 209         public static let setCookie2
 210         public static let setProfile
 211         public static let slug
 212         public static let soapAction
 213         public static let statusURI
 214         public static let strictTransportSecurity
 215         public static let surrogateCapability
 216         public static let surrogateControl
 217         public static let tcn
 218         public static let te
 219         public static let timeout
 220         public static let topic
 221         public static let trailer
 222         public static let transferEncoding
 223         public static let ttl
 224         public static let urgency
 225         public static let uri
 226         public static let upgrade
 227         public static let userAgent
 228         public static let variantVary
 229         public static let vary
 230         public static let via
 231         public static let wwwAuthenticate
 232         public static let wantDigest
 233         public static let warning
 234         public static let xFrameOptions
 235
 236         // https://www.iana.org/assignments/message-headers/message-headers.xhtml
 237         // Provisional Message Header Field Names
 238         public static let accessControl
 239         public static let accessControlAllowCredentials
 240         public static let accessControlAllowHeaders
 241         public static let accessControlAllowMethods
 242         public static let accessControlAllowOrigin
 243         public static let accessControlMaxAge
 244         public static let accessControlRequestMethod
 245         public static let accessControlRequestHeaders
 246         public static let compliance
 247         public static let contentTransferEncoding
 248         public static let cost
 249         public static let ediintFeatures
 250         public static let messageID
 251         public static let methodCheck
 252         public static let methodCheckExpires
 253         public static let nonCompliance
 254         public static let optional
 255         public static let refererRoot
 256         public static let resolutionHint
 257         public static let resolverLocation
 258         public static let subOK
 259         public static let subst
 260         public static let title
 261         public static let uaColor
 262         public static let uaMedia
 263         public static let uaPixels
 264         public static let uaResolution
 265         public static let uaWindowpixels
 266         public static let version
 267         public static let xDeviceAccept
 268         public static let xDeviceAcceptCharset
 269         public static let xDeviceAcceptEncoding
 270         public static let xDeviceAcceptLanguage
 271         public static let xDeviceUserAgent
 272     }
 273 }
 274
 275 /// Version number of the HTTP Protocol
 276 public struct HTTPVersion {
 277     /// Major version component.
 278     public var major: Int
 279     /// Minor version component.
 280     public var minor: Int
 281
 282     public init(major: Int, minor: Int)
 283 }
 284
 285 public enum HTTPTransferEncoding {
 286     case identity(contentLength: UInt)
 287     case chunked
 288 }
 289
 290 /// Response status (200 ok, 404 not found, etc)
 291 public struct HTTPResponseStatus: Equatable, CustomStringConvertible, ExpressibleByIntegerLiteral {
 292     public let code: Int
 293     public let reasonPhrase: String
 294
 295     public init(code: Int, reasonPhrase: String)
 296     public init(code: Int)
 297
 298     /* all the codes from http://www.iana.org/assignments/http-status-codes */
 299     public static let `continue`
 300     public static let switchingProtocols
 301     public static let ok
 302     public static let created
 303     public static let accepted
 304     public static let nonAuthoritativeInformation
 305     public static let noContent
 306     public static let resetContent
 307     public static let partialContent
 308     public static let multiStatus
 309     public static let alreadyReported
 310     public static let imUsed
 311     public static let multipleChoices
 312     public static let movedPermanently
 313     public static let found
 314     public static let seeOther
 315     public static let notModified
 316     public static let useProxy
 317     public static let temporaryRedirect
 318     public static let permanentRedirect
 319     public static let badRequest
 320     public static let unauthorized
 321     public static let paymentRequired
 322     public static let forbidden
 323     public static let notFound
 324     public static let methodNotAllowed
 325     public static let notAcceptable
 326     public static let proxyAuthenticationRequired
 327     public static let requestTimeout
 328     public static let conflict
 329     public static let gone
 330     public static let lengthRequired
 331     public static let preconditionFailed
 332     public static let payloadTooLarge
 333     public static let uriTooLong
 334     public static let unsupportedMediaType
 335     public static let rangeNotSatisfiable
 336     public static let expectationFailed
 337     public static let misdirectedRequest
 338     public static let unprocessableEntity
 339     public static let locked
 340     public static let failedDependency
 341     public static let upgradeRequired
 342     public static let preconditionRequired
 343     public static let tooManyRequests
 344     public static let requestHeaderFieldsTooLarge
 345     public static let unavailableForLegalReasons
 346     public static let internalServerError
 347     public static let notImplemented
 348     public static let badGateway
 349     public static let serviceUnavailable
 350     public static let gatewayTimeout
 351     public static let httpVersionNotSupported
 352     public static let variantAlsoNegotiates
 353     public static let insufficientStorage
 354     public static let loopDetected
 355     public static let notExtended
 356     public static let networkAuthenticationRequired
 357
 358     public var `class`: Class
 359
 360     public enum Class {
 361         case informational
 362         case successful
 363         case redirection
 364         case clientError
 365         case serverError
 366         case invalidStatus
 367     }
 368 }
 369
 370 /// HTTP Methods handled by http_parser.[ch] supports
 371 public struct HTTPMethod : Hashable, CustomStringConvertible, ExpressibleByIntegerLiteral {
 372
 373     public let method: String
 374
 375     public init(_ method: String)
 376
 377     /* Constants for everything that http_parser.[ch] supports */
 378     public static let delete
 379     public static let get
 380     public static let head
 381     public static let post
 382     public static let put
 383     public static let connect
 384     public static let options
 385     public static let trace
 386     public static let copy
 387     public static let lock
 388     public static let mkcol
 389     public static let move
 390     public static let propfind
 391     public static let proppatch
 392     public static let search
 393     public static let unlock
 394     public static let bind
 395     public static let rebind
 396     public static let unbind
 397     public static let acl
 398     public static let report
 399     public static let mkactivity
 400     public static let checkout
 401     public static let merge
 402     public static let msearch
 403     public static let notify
 404     public static let subscribe
 405     public static let unsubscribe
 406     public static let patch
 407     public static let purge
 408     public static let mkcalendar
 409     public static let link
 410     public static let unlink
 411 }
 412 ```