From 667619e66b1c7f6e584029d4806c1208f16df30c Mon Sep 17 00:00:00 2001 From: Peter Adams Date: Fri, 12 Aug 2022 14:37:06 +0100 Subject: [PATCH] Simple index pages for docc Motivation: An index page ties all the other documentation together Modifications: Add index pages for the library targets. Correct a few minor errors in the main docs. Result: A more joined up documentation experience. --- Sources/NIOExtras/Docs.docc/Article.md | 13 ------ Sources/NIOExtras/Docs.docc/index.md | 43 +++++++++++++++++++ Sources/NIOExtras/WritePCAPHandler.swift | 2 +- .../Documentation.docc/index.md | 27 ++++++++++++ .../HTTPDecompression.swift | 1 + Sources/NIOSOCKS/Docs.docc/index.md | 35 +++++++++++++++ 6 files changed, 107 insertions(+), 14 deletions(-) delete mode 100644 Sources/NIOExtras/Docs.docc/Article.md create mode 100644 Sources/NIOExtras/Docs.docc/index.md create mode 100644 Sources/NIOHTTPCompression/Documentation.docc/index.md create mode 100644 Sources/NIOSOCKS/Docs.docc/index.md diff --git a/Sources/NIOExtras/Docs.docc/Article.md b/Sources/NIOExtras/Docs.docc/Article.md deleted file mode 100644 index ed5c0a4..0000000 --- a/Sources/NIOExtras/Docs.docc/Article.md +++ /dev/null @@ -1,13 +0,0 @@ -# Article - -Summary - -## Overview - -Text - -## Topics - -### Group - -- ``Symbol`` diff --git a/Sources/NIOExtras/Docs.docc/index.md b/Sources/NIOExtras/Docs.docc/index.md new file mode 100644 index 0000000..e971695 --- /dev/null +++ b/Sources/NIOExtras/Docs.docc/index.md @@ -0,0 +1,43 @@ +# NIOExtras + +A collection of helpful utilities to assist in building and debugging Swift-NIO based applications. + +## Overview + +A collection of helpful utilities to assist in building and debugging Swift-NIO based applications. Topics covered include packet capture, the logging of channel pipeline events, frame decoding of various common forms and helpful data types. + +Debugging aids include `ChannelHandler`s to log channel pipeline events both inbound and outbound; and a `ChannelHandler` to log data in packet capture format. + +To support encoding and decoding helpers are provided for data frames which have fixed length; are new line terminated; contain a length prefix; or are defined by a `context-length` header. + +To help simplify building a robust pipeline the ``ServerQuiescingHelper`` makes it easy to collect all child `Channel`s that a given server `Channel` accepts. + +Easy request response flows can be built using the ``RequestResponseHandler`` which takes a request and a promise which is fulfilled when an expected response is received. + +## Topics + +### Debugging Aids + +- ``DebugInboundEventsHandler`` allows logging of inbound channel pipeline events. +- ``DebugOutboundEventsHandler`` allows logging of outbound channel pipeline events. +- ``NIOWritePCAPHandler``captures data from the channel pipeline in PCAP format. +- ``NIOPCAPRingBuffer`` stores captured packet data. + +### Encoding and Decoding + +- ``FixedLengthFrameDecoder`` splits received data into frames of a fixed number of bytes. +- ``NIOJSONRPCFraming`` emits JSON-RPC wire protocol with 'Content-Length' HTTP-like headers. +- ``LengthFieldBasedFrameDecoder`` splits received data into frames based on a length header in the data stream. +- ``NIOLengthFieldBasedFrameDecoderError`` contains errors emitted from ``LengthFieldBasedFrameDecoder`` +- ``LengthFieldPrepender`` is an encoder that takes a `ByteBuffer` message and prepends the number of bytes in the message. +- ``LengthFieldPrependerError`` contains errors emitted from ``LengthFieldPrepender`` +- ``LineBasedFrameDecoder`` splits received data into frames terminated by new lines. +- ``NIOExtrasErrors`` contains errors emitted from the NIOExtras decoders. +- ``NIOExtrasError`` base type for ``NIOExtrasErrors`` + +### Channel Pipeline Aids +- ``ServerQuiescingHelper`` makes it easy to collect all child `Channel`s that a given server `Channel` accepts. +- ``RequestResponseHandler`` takes a request and a promise which is fulfilled when expected response is received. + +### Data Types +- ``NIOLengthFieldBitLength`` describes the length of a piece of data in bits diff --git a/Sources/NIOExtras/WritePCAPHandler.swift b/Sources/NIOExtras/WritePCAPHandler.swift index 8ace0bb..92bcf4e 100644 --- a/Sources/NIOExtras/WritePCAPHandler.swift +++ b/Sources/NIOExtras/WritePCAPHandler.swift @@ -184,7 +184,7 @@ public class NIOWritePCAPHandler: RemovableChannelHandler { private var localAddress: SocketAddress? private var remoteAddress: SocketAddress? - /// Reusable header for `. pcap` file. + /// Reusable header for `.pcap` file. public static var pcapFileHeader: ByteBuffer { var buffer = ByteBufferAllocator().buffer(capacity: 24) buffer.writePCAPHeader() diff --git a/Sources/NIOHTTPCompression/Documentation.docc/index.md b/Sources/NIOHTTPCompression/Documentation.docc/index.md new file mode 100644 index 0000000..4414dfa --- /dev/null +++ b/Sources/NIOHTTPCompression/Documentation.docc/index.md @@ -0,0 +1,27 @@ +# NIOHTTPCompression + +Automatic compression and decompression of HTTP data. + +## Overview + +Channel handlers to support automatic compression and decompression of HTTP data. Add the handlers to your pipeline to support the features you need. + +`Content-Encoding`, `Content-Length`, and `accept-encoding` HTTP headers are set and respected where appropriate. + +Be aware that this works best if there is sufficient data written between flushes. This also performs compute on the event loop thread which could impact performance. + +## Topics + +### Client Channel Handlers + +- ``NIOHTTPRequestCompressor`` +- ``NIOHTTPResponseDecompressor`` + +### Server Channel Handlers +- ``NIOHTTPRequestDecompressor`` +- ``HTTPResponseCompressor`` + +### Compression Methods + +- ``NIOCompression`` +- ``NIOHTTPDecompression`` diff --git a/Sources/NIOHTTPCompression/HTTPDecompression.swift b/Sources/NIOHTTPCompression/HTTPDecompression.swift index 9bf6b51..e4531d3 100644 --- a/Sources/NIOHTTPCompression/HTTPDecompression.swift +++ b/Sources/NIOHTTPCompression/HTTPDecompression.swift @@ -15,6 +15,7 @@ import CNIOExtrasZlib import NIOCore +/// Namespace for decompression code. public enum NIOHTTPDecompression { /// Specifies how to limit decompression inflation. public struct DecompressionLimit { diff --git a/Sources/NIOSOCKS/Docs.docc/index.md b/Sources/NIOSOCKS/Docs.docc/index.md new file mode 100644 index 0000000..6f7e054 --- /dev/null +++ b/Sources/NIOSOCKS/Docs.docc/index.md @@ -0,0 +1,35 @@ +# NIOSOCKS + +SOCKS v5 protocol implementation + +## Overview + +An implementation of SOCKS v5 protocol. See [RFC1928](https://www.rfc-editor.org/rfc/rfc1928). + +Add the appropriate channel handler to the start of your channel pipeline to use this protocol. + +For an example see the NIOSOCKSClient target. + +## Topics + +### Channel Handlers +- ``SOCKSClientHandler`` connects to a SOCKS server to establish a proxied connection to a host. +- ``SOCKSServerHandshakeHandler`` server side SOCKS channel handler. + +### Client Messages +- ``ClientMessage`` message types from the client to the server. +- ``ClientGreeting`` client initiation of SOCKS handshake. +- ``SOCKSRequest`` the target host and how to connect. + +### Server Messages +- ``ServerMessage`` message types from the server to the client. +- ``SelectedAuthenticationMethod`` the authentication method selected by the SOCKS server. +- ``SOCKSResponse`` the server response to the client request. + +### Supporting Types +- ``AuthenticationMethod`` The SOCKS authentication method to use. +- ``SOCKSServerReply`` indicates the success or failure of connection. +- ``SOCKSCommand`` the type of connection to establish. +- ``SOCKSAddress`` the address used to connect to the target host. +- ``SOCKSProxyEstablishedEvent`` a user event that is sent when a SOCKS connection has been established. +- ``SOCKSError`` socks protocol errors which can be emitted.