Hardcoded IO in generated code

[jducoeur]

Context: https://softwaremill.community/t/how-best-to-go-about-proposing-and-helping-with-code-generation-improvements/542

Tapir version: 1.13.19

If you have a lazy type (eg, a default binary octet stream) specified as the body, the code generator sets up an fs2 Stream, as it should. Unfortunately, it hardcodes the effect of that Stream as IO.

That's often correct, but if you're in an environment that is trying to be effect-neutral (as our services are), it's basically unusable. We're admittedly a little unusual in following tagless final in services, but this problem would be a blocker for any library that follows Typelevel best practices. (And heaven knows I've written my share of libraries that were built around an external OpenAPI spec.)

For now, I've hacked our first OpenAPI spec to require the incoming file to be defined as an eager String, but that's pretty awful -- counter to both Tapir's and our own architectural best practices.

I think what I'm hoping for here is a feature flag that causes the generated code to be abstract in F[_], so that it plays nicely in a tagless-final environment. Does that seem appropriate? I'm happy to work on this, if so.

[adamw]

Yes, an option for the openapi-codegen seems appropriate. If you could take a shot, it would be great.

(cc @hughsimpson, just FYI here)

[jducoeur]

Okay, cool. I'm starting the process of figuring out what hoops I need to jump through in order to contribute (this is for dayjob, so I need to run it through the enterprise's open-source-development channels), but hopefully that won't take too long.

[hughsimpson]

I think you can already hack this?

[hughsimpson]

openapiStreamingImplementation := "fs2-com.myco.pkg.utils.TracingUtils.NotAnIO" under build settings?

[hughsimpson]

I use trace4cats myself and needed that ... Possibly the same situation? ;)

[jducoeur]

TIL (and it's kind of obscure), but I'll give it a look -- thanks!

[hughsimpson]

Yeah a lot of this stuff has issues. I've been using source code generator plugins to hack around it for years 😅 I'll try to upstream some stuff next week

[hughsimpson]

An impl might look like type NotAnIO[T] = Kleisli[IO, Span[IO], T]. Mine does anyway lol

[hughsimpson]

Sorry it's a bit hostile to new contributors. I've known for ages that the codebase needs a refactor but I only ever have time when it's feature'o'clock :(

[hughsimpson]

@jducoeur sorry, I was pints deep on Friday night if that wasn't screamingly obvious. Did the fs2-my.Monad syntax work out?

[jducoeur]

Haven't had a chance to try yet, sorry -- in the middle of a dozen projects at work, and while I care about this topic in the name of good clean code (and specs), it's not actually blocking anything.

[jducoeur]

Okay -- I sat down with this today, kicked the tires, and had a conversation with Opus to help get my thoughts straight.

The answer seems to be that no, the openapiStreamingImplementation hack doesn't fix this situation -- moreover, I think it can't do so.

The problem has to do with shapes and data flow. The generator as it currently works assumes that the effect for FS2 is a concrete class of the shape M[_]. That's fine for most situations.

The problem is that (I think) it's fundamentally incompatible with effect-polymorphic environments, where the effect has a shape like F[_]: Async. That is, the effect itself is abstract -- just a type parameter -- with a context bound defining its capabilities. That context bound is key: to be able to do this sort of thing, you have to be passing an implicit/given type class instance around.

(Granted, my team are a little unusual (although not rare) in having decided to build services that way. But it's bog-standard for Typelevel-style libraries, so I think this has the effect that the code generator can't currently be used in such libraries. That's a little unfortunate: while it is, again, an unusual use case, it's not unheard-of -- there are times when it's useful for sharing abstractions around an API.)

Fixing this one isn't trivial, because it cuts to the shape of how the entry points are defined. They're currently all lazy vals inside objects, so there's nowhere to put a type parameter. Making it work requires that the object become a class, or (more likely) that the lazy val become a def, so that it's possible to pass in a context bound.

So it would produce code that is markedly different -- although, weirdly, I'm not sure how much that difference would matter in practice. Currently, the effect is being hard-coded at the bottom and propagated up to the type signature from there. Changing this would mean that the effect type potentially gets inferred at the call site instead. It's possible that this would work without requiring any changes at the call site, although I can't say I necessarily count on the Scala compiler to be reliable enough for that to always work.

Anyway, I think it's a big-deal change, and not easy. I recommend it -- I think it's fairly critical for working with effect-parameterized environments like ours -- but I'm definitely not demanding it. If I can find my way through the bureaucracy to be allowed to make PRs myself, I'll take a stab at it. (No sooner than next month, sadly.)

[hughsimpson]

You could actually do it with a source code generator... String replace the object MyEndpoints to a class MyEndpoints[T[_] : ...] and just use fs2-T as your effect type. But I don't think, if you're using abstract types, you're somewhere I wanna support by default (ie such functionality should be opt-in, rather than opt-out). Having endpoint definitions exist as compiled on an object is an important usability baseline IMO. But I don't think you'd need to dig deeper than Root to add native support.

Changing all the call sites would be way harder. Hopefully at class level it'd be flexible enough

[hughsimpson]

I never liked free monads anyway. I find a core monad type way more usable IRL, and if you're not building a library, why so many monads? But that's a taste thing I guess. More importantly, do you see what I'm getting at with the suggestion? You build the endpoint class with your type param.

Transparency: I've been relying on last-mile sourcecode generator munging since the get go when using this project (although much less now that it supports dedup natively), and it would be nice for it to be so flexible and configurable that that wasn't a need... But it's nonetheless a very valid way to make extra customisations IMO.

[hughsimpson]

Maybe we could just bake in munge rules to the plugin