feat(server): Add support for encoded source files

[GreenGremlin]

This change allows preprocessors to specify an encoding for files. Currently, if a preprocessor encodes a file in a format such as gzip or Brotli, the file is served with the wrong encoding. The only workaround for this is to also include a plugin (example) that removes encoded files from files.served and serves them manually using a custom file handler. This approach is a gross hack that unnecessarily complicates the encoding plugin's logic.

With this change, a preprocessor encodes the contents and stores them in the File class' new encodings property. The encodings property is a keyed object where the keys are the encoding type ('gzip', 'compress', 'br', etc.) and the values are the encoded content. This pattern has the advantage of allowing multiple encoders and serving the encoding that best matches the request. It also allows the unencoded content to be served, when no encoding matches the request.

I know there has been pushback on adding encoding support, but I'm hoping this approach is an acceptable compromise. This solution leaves pretty much all encoding logic to the preprocessors and minimizes karma's role as much as possible.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[GreenGremlin]

CLA signed

[googlebot]

CLAs look good, thanks!

[johnjbarton]

You mentioned pushback, can you point to it so I can understand the issue. Your approach looks good to me.

Can you add a short bit of documentation to dev/plugins.html under preprocessors?
I'm thinking of a slight re-write of your commit description:

a preprocessor encodes the contents and stores them in the File class' new encodings property. The encodings property is a keyed object where the keys are the encoding type ('gzip', 'compress', 'br', etc.) and the values are the encoded content.

[GreenGremlin]

You mentioned pushback, can you point to it so I can understand the issue. Your approach looks good to me.

I updated the description and added a link to [the issue](This #1241) in which there was pushback.

[GreenGremlin]

Can you add a short bit of documentation to dev/plugins.html under preprocessors?
I'm thinking of a slight re-write of your commit description:

Done. It felt odd to document only the encodings property of the file object, so I added documentation for all three arguments passed to preprocessors. For the file argument, I documented the path, originalPath, encodings, and type properties. I did not document contentPath, mtime, isUrl, and doNotCache; because they seemed more internal to karma and not really related to preprocessors. Let me know if you'd like me to document any of the properties I did not document, or if you'd like me to remove any of the properties I did document.

[johnjbarton]

I think your feature is more general than the feature request that was rejected earlier. It fits into karma's architecture, allowing other plugins without a large impact on the core code.