CLI Option to Remove the 'sl-violations' Header in Responses

[travisgosselin]

User Story Description

As an API Producer creating an API and using the Prism Validation Proxy to log all traffic that doesn't correspond with my Open API specification, I want to be able to disable the "sl-violations" headers in the response so I do not have to communicate all the violations to the consumer.

Additionally on endpoints with many violations having a structured json object in the header does eventually overflow. This can cause runtime issues where some requests work and others fail on platforms that overflow the header length. This is especially true in a collection or search style endpoint where I may get a violation for EVERY object in the collection returned making a massive HEADER that is unsupported in some platforms by default. While not in error mode, the proxy should NEVER fail as a result of differences.

Acceptance Criteria

• [ ] A new command line option to disable the sl-violations header in the response is available.

Sprint Ready Checklist

• [ ] Acceptance criteria defined
• [ ] Team understands acceptance criteria
• [ ] Team has defined solution/steps to satisfy acceptance criteria
• [ ] Acceptance criteria is verifiable/testable
• [ ] External / 3rd Party dependencies identified

[chohmann]

We'd like some clarification on a couple things:

1. Why are you using Prism as a proxy if you don't want the violation information to be provided in the header? That's the main purpose for using prism proxy, so we are interested in learning your use case.
2. Who are you trying to hide the violation information from? Your customers? Other frontend engineers?
3. FYI, we've already completed #2129 which will prevent your concern of the sl-violations header from getting too long. Have you tried this? If you're using the latest version that has this fix, what tool are you using that is breaking?
4. We do not understand what you mean by "While not in error mode, the proxy should NEVER fail as a result of differences." Could you provide further clarification.

[travisgosselin]

Thanks for the quick response @chohmann . I'll try and provide some context and answers to your questions.

Why are you using Prism as a proxy if you don't want the violation information to be provided in the header? That's the main purpose for using prism proxy, so we are interested in learning your use case.

Good question! We consume the violations based on log output that we can aggregate across our organization and monitor for compliance. This same log output is used to produce alerts on differences. We do not consume sl-violations as part of our integrations testing, though we may do that in the future. However, even as such, we'd like to enable the proxy validation in PROD where sl-violations are not part of the contract of returned headers that customers or other users would see (for internal usage only). On this topic, the log output from Prism Proxy is also very tough to parse in a contextual way programmatically. I know this is completely off-topic, but having a structured single-line output format would really make using the log output a lot simpler in an aggregated way (topic for another time).

Who are you trying to hide the violation information from? Your customers? Other front-end engineers?

We would like to hide this header from our external contract to customers so we can use our internal logs and alerts to improve consistency without exposing the header. In some cases as well, we are putting the proxy in place knowing there is a WIDE separation of compliance, and expect a lot of differences while our teams work towards compliance.

FYI, we've already completed https://github.com/stoplightio/prism/issues/2129 which will prevent your concern of the sl-violations header from getting too long. Have you tried this? If you're using the latest version that has this fix, what tool are you using that is breaking?

OK great this good to know there is maximum truncation already placed on it. This is sitting behind a custom API Gateway that we have for our internal developer platform. It must have a lower limit. I also see that there is a reference to the same request a year ago, with the ability to remove the header for similar reasons. In our case for both size issues of an upstream gateway but also for keeping the contract smaller/hidden would be ideal.

We do not understand what you mean by "While not in error mode, the proxy should NEVER fail as a result of differences." Could you provide further clarification?

Sorry, this is my poor wording. What I mean by "not in error mode" is that when --errors false it should NEVER provide a different result than the API provided (i.e. in my case be the upstream culprit of large headers in my system dynamically based on payload size/deviations), whereas with --errors true it provides ERROR payloads/status code on non-compliance (which is great).

Hope that helps - looking forward to hearing your thoughts!

[chohmann]

@travisgosselin thank you for clarifying your use case! We never anticipated or planned for Prism to be used in a production environment, but can see some value in how you're using it in your production system.

it should NEVER provide a different result than the API provided

This is a key insight into a need for Prism to have the ability to be completely transparent from the client perspective. In this mode Prism will still evaluate and log differences in contract, but the outgoing response remains unchanged from the upstream server.

We prefer this approach over removing the sl-violations header, and gladly welcome PRs to introduce this.

Here's some details on the approach we prefer:

• add a new modes to Prism separate from mock and proxy (i.e. prism transparent-proxy ... or other name)
• we would need to evaluate which of the existing options for proxy pertain to this new modes and how they should behave
  • more specifically, which options affect what log output is produced since we would need to maintain that since it's the value add for this new modes
• nothing changes on request/response validation side of things, so the appropriate logs are still produced, we would just not modify the request or response in any way

We'd love to see a new structured log format as that would benefit all of Prism's modes, current and this proposed one.

While we think this is a very interesting use case, we will likely not have capacity to introduce this ourselves in near future. We welcome PRs from you or other community members to introduce this proposed functionality.

[travisgosselin]

Thanks @chohmann your last response is helpful to understand the positioning of PRISM and your future roadmap plans. Some general thoughts inline below:

We never anticipated or planned for Prism to be used in a production environment, but can see some value in how you're using it in your production system.

This is very good to know. In your documentation, you have a section for the Prism CLI called "Running in Production" which led me to believe that this was a valid use case. Might be helpful to update that section with a bit more context to set the expectation. For now, we will continue applying full Prism Validation Proxy with errors enabled on mismatch in our "test" environment and step more slowly into seeing how this materializes in our production environment in scenarios like this.

We prefer this approach over removing the sl-violations header, and gladly welcome PRs to introduce this.

Excellent! I'm disappointed to hear it is not on your roadmap, but glad you are interested in accepting some PRs. As we introduce this into our production environment, will consider and prioritize accordingly if we can contribute this functionality to enable our production environment with this!

We'd love to see a new structured log format as that would benefit all of Prism's modes, current and this proposed one.

Great - glad that there is interest in a more machine-friendly output.

We will advise in the future if we are able to contribute some effort here. Thanks again for considering and reviewing this :)