dnrops
/
swift-nio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
Johannes Weiss 2019-04-05 17:22:44 +01:00 committed by GitHub
parent fef050a83c
commit 39c6b87ff8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/migration-guide-NIO1-to-NIO2.md
View File

@ -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 ## 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. - 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.