Update release notes & documentation.

Author: ioquatix

context/extensions.md

@@ -0,0 +1,91 @@
+# Extensions
+
+This guide explains how to use `protocol-websocket` for implementing a websocket client and server using extensions.
+
+## Per-message Deflate
+
+WebSockets have a mechanism for implementing extensions. At the time of writing, the only published extension is `permessage-deflate` for per-message compression. It operates on complete messages rather than individual frames.
+
+Clients and servers can negotiate a set of extensions to use. The server can accept or reject these extensions. The client can then instantiate the extensions and apply them to the connection. More specifically, clients need to define a set of extensions they want to support:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/extensions'
+
+client_extensions = Protocol::WebSocket::Extensions::Client.new([
+	[Protocol::WebSocket::Extension::Compression, {}]
+])
+
+offer_headers = []
+
+client_extensions.offer do |header|
+	offer_headers << header.join(';')
+end
+
+offer_headers # => ["permessage-deflate;client_max_window_bits"]
+~~~
+
+This is transmitted to the server via the `Sec-WebSocket-Extensions` header. The server processes this and returns a subset of accepted extensions. The client receives a list of accepted extensions and instantiates them:
+
+~~~ ruby
+server_extensions = Protocol::WebSocket::Extensions::Server.new([
+	[Protocol::WebSocket::Extension::Compression, {}]
+])
+
+accepted_headers = []
+
+server_extensions.accept(offer_headers) do |header|
+	accepted_headers << header.join(';')
+end
+
+accepted_headers # => ["permessage-deflate;client_max_window_bits=15"]
+
+client_extensions.accept(accepted_headers)
+~~~
+
+We can check the extensions are accepted:
+
+~~~ ruby
+server_extensions.accepted
+# => [[Protocol::WebSocket::Extension::Compression, {:client_max_window_bits=>15}]]
+
+client_extensions.accepted
+# => [[Protocol::WebSocket::Extension::Compression, {:client_max_window_bits=>15}]]
+~~~
+
+Once the extensions are negotiated, they can be applied to the connection:
+
+~~~ ruby
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+client_extensions.apply(client)
+server_extensions.apply(server)
+
+# We can see that the appropriate wrappers have been added to the connections:
+client.reader.class # => Protocol::WebSocket::Extension::Compression::Inflate
+client.writer.class # => Protocol::WebSocket::Extension::Compression::Deflate
+server.reader.class # => Protocol::WebSocket::Extension::Compression::Inflate
+server.writer.class # => Protocol::WebSocket::Extension::Compression::Deflate
+
+client.send_text("Hello World")
+# => #<Protocol::WebSocket::TextFrame:0x000000011d555460 @finished=true, @flags=4, @length=13, @mask=nil, @opcode=1, @payload="\xF2H\xCD\xC9\xC9W\b\xCF/\xCAI\x01\x00">
+
+server.read
+# => #<Protocol::WebSocket::TextMessage:0x000000011e1e5248 @buffer="Hello World">
+~~~
+
+It's possible to disable compression on a per-message basis:
+
+~~~ ruby
+client.send_text("Hello World", compress: false)
+# => #<Protocol::WebSocket::TextFrame:0x00000001028945b0 @finished=true, @flags=0, @length=11, @mask=nil, @opcode=1, @payload="Hello World">
+
+server.read
+# => #<Protocol::WebSocket::TextMessage:0x000000011e77eb50 @buffer="Hello World">
+~~~

context/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+This guide explains how to use `protocol-websocket` for implementing a websocket client and server.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add protocol-websocket
+~~~
+
+## Core Concepts
+
+`protocol-websocket` has several core concepts:
+
+- A {ruby Protocol::WebSocket::Frame} is the base class which is used to represent protocol-specific structured frames.
+- A {ruby Protocol::WebSocket::Framer} wraps an underlying {ruby Async::IO::Stream} for reading and writing binary data into structured frames.
+- A {ruby Protocol::WebSocket::Connection} wraps a framer and implements for implementing connection specific interactions like reading and writing text.
+- A {ruby Protocol::WebSocket::Message} is a higher-level abstraction for reading and writing messages.
+
+## Bi-directional Communication
+
+We can create a small bi-directional WebSocket client server:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+client.send_text("Hello World")
+server.read
+# #<Protocol::WebSocket::TextMessage:0x000000011d2338e0 @buffer="Hello World">
+
+client.send_binary("Hello World")
+server.read
+#<Protocol::WebSocket::BinaryMessage:0x000000011d371db0 @buffer="Hello World">
+~~~
+
+## Messages
+
+We can also use the {ruby Protocol::WebSocket::Message} class to read and write messages:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+# Encode a value using JSON:
+message = Protocol::WebSocket::TextMessage.generate({hello: "world"})
+
+client.write(message)
+server.read.to_h
+# {:hello=>"world"}
+~~~
+
+### Text Messages
+
+Text messages contain UTF-8 encoded text. Invalid UTF-8 sequences will result in errors. Text messages are useful for sending structured data like JSON.
+
+### Binary Messages
+
+Binary messages contain arbitrary binary data. They can be used to send any kind of data. Binary messages are useful for sending files or other binary data, like images or video.

context/index.yaml

@@ -0,0 +1,16 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A low level implementation of the WebSocket protocol.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-websocket/
+  source_code_uri: https://github.com/socketry/protocol-websocket.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `protocol-websocket` for implementing
+    a websocket client and server.
+- path: extensions.md
+  title: Extensions
+  description: This guide explains how to use `protocol-websocket` for implementing
+    a websocket client and server using extensions.

protocol-websocket.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 		"source_code_uri" => "https://github.com/socketry/protocol-websocket.git",
 	}
 
-	spec.files = Dir.glob(["{lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)
+	spec.files = Dir.glob(["{context,lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)
 
 	spec.required_ruby_version = ">= 3.3"
 

readme.md

@@ -14,7 +14,49 @@ Please see the [project documentation](https://socketry.github.io/protocol-webso
 
 ## Releases
 
-There are no documented releases.
+Please see the [project releases](https://socketry.github.io/protocol-websocket/releases/index) for all releases.
+
+### Unreleased
+
+  - All frame reading and writing logic has been consolidated into `Framer` to improve performance.
+
+### v0.20.2
+
+  - Fix error messages for `Frame` to be more descriptive.
+
+### v0.20.1
+
+  - Revert masking enforcement option introduced in v0.20.0 due to compatibility issues.
+
+### v0.20.0
+
+  - Introduce option `requires_masking` to `Framer` for enforcing masking on received frames.
+
+### v0.19.1
+
+  - Ensure ping reply payload is packed correctly.
+
+### v0.19.0
+
+  - Default to empty string for message buffer when no data is provided.
+
+### v0.18.0
+
+  - Add `PingMessage` alongside `TextMessage` and `BinaryMessage` for a consistent message interface.
+  - Remove `JSONMessage` (use application-level encoding instead).
+
+### v0.17.0
+
+  - Introduce `#close_write` and `#shutdown` methods on `Connection` for more precise connection lifecycle control.
+
+### v0.16.0
+
+  - Move `#send` logic into `Message` for better encapsulation.
+  - Improve error handling when a `nil` message is passed.
+
+### v0.15.0
+
+  - Require `Message` class by default.
 
 ## Contributing
 

releases.md

@@ -1,3 +1,43 @@
 # Releases
 
 ## Unreleased
+
+  - All frame reading and writing logic has been consolidated into `Framer` to improve performance.
+
+## v0.20.2
+
+  - Fix error messages for `Frame` to be more descriptive.
+
+## v0.20.1
+
+  - Revert masking enforcement option introduced in v0.20.0 due to compatibility issues.
+
+## v0.20.0
+
+  - Introduce option `requires_masking` to `Framer` for enforcing masking on received frames.
+
+## v0.19.1
+
+  - Ensure ping reply payload is packed correctly.
+
+## v0.19.0
+
+  - Default to empty string for message buffer when no data is provided.
+
+## v0.18.0
+
+  - Add `PingMessage` alongside `TextMessage` and `BinaryMessage` for a consistent message interface.
+  - Remove `JSONMessage` (use application-level encoding instead).
+
+## v0.17.0
+
+  - Introduce `#close_write` and `#shutdown` methods on `Connection` for more precise connection lifecycle control.
+
+## v0.16.0
+
+  - Move `#send` logic into `Message` for better encapsulation.
+  - Improve error handling when a `nil` message is passed.
+
+## v0.15.0
+
+  - Require `Message` class by default.