Principled code generation from OpenAPI specifications. https://guardrail.dev/
the challenge comes from ensuring proper round trip for string-interpolated values, so this likely would rely on the Uri classes available for each framework
Hi! Firstly, thank you so much for all of the work on this project. I just found it the other day and hoping to possibly begin driving adoption at work. I noticed an issue hanging out about tracing, and was curious if there was already any in-progress work. If not, I’d love to help out here, as I’m gonna need to figure it out for our use anyway.
In my head, my approach would be to inject a parent span (not TraceBuilder) into each method of the handlers. I believe that with that, it would allow some more granular “internal” instrumentation, while continuing to allow the trace to be started (or continued in a distributed model) from request handling, and finished on the response. It’s also entirely possible that this is feasible today, and I’m not following what exists.
Yeah --
TraceBuilder is really a relic, considering the new request/response transformers. I was initially against having those, as they permit complete violation of the spec or schema, but after wrestling with TraceBuilder for so long, I was really brought around to the more pragmatic, general solution.
I'm glad you find the project helpful!
I certainly don’t love the idea of custom extract because of the ability to violate the spec, but I think it is easier to have discipline in one place (the custom extractor) than relying on having discipline across your whole API. If I got worried about abuse, I could always create a more constrained abstraction on top to avoid it getting used “for evil” 😂
Yeah, certainly. Plus, it gives rise to the possibility for a
guardrail-contrib library dependency that fits that function signature to add a bit more structure, in a modular way
Otherwise I’ll test it out here in a project and if it works I’ll extract it!
The
TraceBuilder stuff was modeled around some abstractions we had in Twilio for integrating with Lightstep, datadog APM wasn't available to use at that time
I'd be happy to see it though. I've got a toddler running around, but I'm trying to carve out some time to finish the 1.0.0 guardrail release, (switching the packages from com.twilio to dev.guardrail, no other API changes other than that)
The migration has already been merged, (0.64.4 was actually already accidentally released under dev.guardrail with the package changes), the only follow-up changes are to sbt-guardrail, guardrail-maven-plugin, and guardrail-gradle-plugin. If any of those strike your fancy, that would be tremendously helpful.
Once the new plugins under the new org are available, my plan is to cut a hotfix on the 0.64.x branch in the old org that includes a log line to advise consumers to switch over to the new org in order to continue getting updates via scala-steward or dependabot
lol, spent an hour trying to figure out why sbt-sonatype wasn't picking up my credentials before I discovered that it sneakily caches the result of
sonatypeProfiles in target/, without any sort of eviction if you fix the problem.
sbt-guardrail 0.64.4 released, matching the dev.guardrail package shift.
For the next few releases, I'm going to override the
organization back to com.twilio and publish the same version to both, to give an opportunity for scala-steward to prompt for upgrades to a version that also prints a warning about the organization change
kelnos: What would you say to splitting the guardrail library into different individual modules? Something like
guardrail-circe, guardrail-http4s, guardrail-dropwizard, or otherwise? A problem I'm trying to solve is to stop the seeming runaway train that is attempted semver split across so many subprojects
guardrail core really doesn't change too terribly much, and splitting the modules out would reduce the number of no-op PRs opened by scala-steward and friends
like http4s may not change at all, but akka changes a bunch or vice versa, and the other party is just going along with the updates because it might impact them
It might make sense to do
guardrail-${language}-${library} as well
with the further added benefit of making each individual codebase more tractable for contributors.
blast_hardcheese: sounds like that could help, but i'm worried about it all being more annoying to release, and also during development when making core changes that are then used in the generators
some magicks for checking to see if the current version has already been published and skipping if so
trying to think of what the implications of the current release flow through the github UI would be though
I really like the release-notes -> publish workflow
might need to write a custom github action :\
also, all this is moot if I can't come up with a good UX for consumption from sbt/maven/gradle
also maybe a little worried about what kind of soup the git tags will look like
a plus would be extensions to guardrail core would just be able to be natively supported directly in the build tooling though
something like
<modules><module><name>http4s</name><clientClass>dev.guardrail.generators.ScalaGenerator.Http4sClientGenerator.ClientTermInterp</clientClass>... where the fqcn's are able to be specified (with sensible defaults) in the pom.xml, and so long as the codegen phase has those dependencies on the classpath everything comes together
thinking ahead, that could open modules up to the community without having to choose which build tool plugin has the features you want.
hah, for instance,
circe-java8 could be spun out without just hanging on in the core forever
this is a big change, I'll write something up and open it as an issue
first though, I'll see whether the UX is compelling.
LOL sbt is really flexible.
+val myCustomHttp4sThing = modules.http4s.client.copy(
+ newGetExtraImports={ tracingEnabled =>
+ import scala.meta._
+ dev.guardrail.Target.pure(List(q"import dev.guardrail.example"))
+ }
+)
lazy val exampleClient = (project in file("example-client"))
.settings(commonSettings)
.settings(
- Compile / guardrailTasks += ScalaClient(file("server.yaml"), pkg="example.client", framework="http4s"),
+ Compile / guardrailTasks += ScalaClient(file("server.yaml"), pkg="example.client", framework="http4s").modules(myCustomHttp4sThing, _.circe.json),
libraryDependencies ++= commonDependencies
)
damn
talk about flexibility and empowering users to work around bugs
sangria-graphql/sangria-akka-http#12 (I'm sorry for straying from REST, I hope you will forgive me)
@nickhudkins No apologies necessary! We use Sangria at work, thanks for everything you guys do!