Skip to content
Permalink
Browse files

migration guide: Info about B2MD (#949)

Motivation:

@tomerd learned the hard way that there were some subtle changes in
B2MDs around intercepting arbitrary channel events. Previously,
intercepting those was illegal but possible. In NIO 2, it's impossible.

Modifications:

add a description for what changed

Result:

easier migrations
  • Loading branch information...
weissi committed Apr 5, 2019
1 parent fef050a commit 39c6b87ff8fafdb8790b6942522947e000599c24
Showing with 8 additions and 0 deletions.
  1. +8 −0 docs/migration-guide-NIO1-to-NIO2.md
@@ -62,3 +62,11 @@ NIO 2 only supports Swift 5 so after the migration you should change the first l
## Step 6: Watch out for more subtle changes

- Make sure you close your `Channel` if there's an unhandled error. Usually, the right thing to do is to invoke `context.close(promise: nil)` when `errorCaught` is invoked on your last `ChannelHandler`. Of course, handle all the errors you know you can handle but `close` on all others. This has always been true for NIO 1 too but in NIO 2 we have removed some of the automatic `Channel` closes in the `HTTPDecoder`s and `ByteToMessageDecoder`s have been removed. Why have they been removed? So a user can opt out of the automatic closure.
- If you have a `ByteToMessageDecoder` or a `MessageToByteEncoder`, you will now need to wrap them before adding them to the pipeline. For example:

```swift
channel.pipeline.addHandler(ByteToMessageHandler(MyExampleDecoder())).flatMap {
channel.pipeline.addHandler(MessageToByteHandler(MyExampleEncoder()))
}
```
- Apart from this, most `ByteToMessageDecoder`s should continue to work. There is however one more subtle change: In SwiftNIO 1, you could (illegally) intercept arbitrary `ChannelInboundHandler` or `ChannelOutboundHandler` events in `ByteToMessageHandler`s. This did never work correctly (because the `ByteToMessageDecoder` driver would then not receive those events anymore). In SwiftNIO 2 this is fixed and you won't receive any of the standard `ChannelHandler` events in `ByteToMessageDecoder`s anymore.

0 comments on commit 39c6b87

Please sign in to comment.
You can’t perform that action at this time.