Deprecation notice

[ruiquelhas]

tl;dr

Unfortunately (or not) hapi-magic-filter is going to be deprecated, but rest assured, there is a nice replacement available (more than one to be precise).

Background

The current test suite is a bit awkward and makes it hard to get 100% code coverage. Also, the implementation mixes validation for all kinds of request payload types - data, stream and file, both when parsed or not, which is not really necessary, because, most of the times, you will just stick to a single combination.

One of things that also bothered me was that it was not possible to use validation at the route level. And that was not easy to add to the existing codebase due to the reasons I mentioned above. And this is, IMHO, a really interesting feature (at least until joi starts to allow custom extensions).

So, instead of cramming the functionality into hapi-magic-filter, I decided to break up the existing stuff into a set of smaller modules, all tied together in a nice little ecosystem that builds on this new route-level validation thingy. This allows each module to have a very specific concern and allows all of them to have 100% code coverage.

Road ahead

From now on, I will stop supporting hapi-magic-filter and I recommend you to drop it and keep reading.

Route-level validation

Route-level validation requires the payload to be parsed (the same as joi). For each different output type defined by the payload settings, you can use one of the following modules:

• houdin — output: 'data'
• thurston — output: 'stream'
• lafayette — output: 'file'

All of the above can be used outside the context of hapi, provided you respect their API.

Server-level validation

Server-level validation (what hapi-magic-filter does) leverages the new route-level validation modules to do most of the work, and in this case, you can choose wether to parse the payload or not, based on your needs. Also, regarding the payload settings, and after the validation goes through, you always get what you asked for in the remaining request lifecycle steps (something that wasn't at all true with hapi-magic-filter).

You can use one (or more) of the following modules for this:

• copperfield — output: 'data', parse: true
• blaine — output: 'data', parse: false
• henning — output: 'stream', parse: true
• burton — output: 'stream', parse: false
• fischbacher — output: 'file', parse: true
• coutts — output: 'file', parse: false

Validation logic

Even the validation logic was extracted into two separate modules, each concerned about a specific step in the flow. The file signature matching is now being done with magik and the validation role in the request lifecycle is now established via configuration using supervizor. Both of them work by themselves in isolation, but the latter only makes sense alongside hapi.

License

Another important change was in the license. I've moved from MIT to BSD-3-Clause just because I think it can be a bit more useful while keeping the most important points of the first, so, eventually, nothing changes for the user.

Final thoughts

I believe this is good for everyone. The new modules are easier to reason about and to maintain (both for me and you), have a smaller storage footprint (less code and narrowed dependencies) and have nice magician names. Honestly, I don't see any drawbacks here, but if you think you really need hapi-magic-filter (believe me, you don't), I'm willing to assign it to a "lead" maintainer or even pass the project ownership to anyone interested. In any case, I'll be keeping the package and code available for now, but I won't be doing any update onwards.