My experience implementing a self service UI in ruby

[filterfish]

My intent of this post is to document and share my experience of using the ruby client library. It is also my intent that this provides constructive feedback and to act as a discussion point. If I've failed in that please let me know and I'll try to clarify. With that in mind please excuse any hyperbolic language in it's born from the somewhat frustrating time during this process!

In October last year I wrote a self service UI app in ruby based on the Kratos ruby client library using the official typescript project as a template. I eventually got it working by comparing the wireshark output of the typescript version with my own. It took a while but I put it down to learning a new system. And even though it took me a while to sort it all out it has worked flawlessly since.

Cut forward 8 months and I decide to port my ruby app to the latest version of kratos, mainly because I want to use the hooks (and to not run old software). No problem! So I read the release notes from 0.4 → 0.5 and 0.5 → 0.6. Ok, so a lot had changed. I updated the Gemfile to reflect the new version, changed the URIs as outlined in the release notes. I looked at the gem documentation. Nothing. Oh well there's always the README.md, so I changed the existing methods to the updated methods and boom everything blow up.

There is a syntax problem with the library for which I've opened a but report for #1426 (which has been fixed). So I modified the gem to at least get around that immediate issue.

This is where it where it all starts to get a bit hazy. Nothing worked but I didn't know if the problem was with my kratos setup or with the ruby code. I compared the ruby code with the typescript code and it looks about right so maybe it's the kratos configuration. So I ran up docker-compose and eventually manage to extract a known good kratos configuration file which is virtually identical to the one I have. So kratos looks good. Next I did the same with the kratos-selfservice-ui-node and get that working. But the typescript code is very similar to my ruby code. This is where I start going round and round in circles! So I took a deep breath and started from scratch. I couldn't even get to_session to work, it throws a stack trace seemingly in rack! This turned out to the kratos library trying to log something by iterating over nil.

This is pretty much the point at which I decided to write this post. As it stands I don't know what to do. In fact I think the only option is to use the typescript version which I'm really trying not to because I don't want to introduce another language (least of all one I have no knowledge of) into a project that already has too many languages.

Problem Areas

The points below summarise the major problems I had and I suspect will act as an impediment, at least in the short term, to people adopting the Ory suite of tools.

Automatically generated OpenAPI client libraries

The API is virtually unusable. I understand why you automatically generate the client code but it is almost unusable: the library documentation is useless and there is one very short example which, at the risk of repeating myself, is virtually useless. I had a look on github to see if anyone else had written something that I could use as an example but there was nothing.

Only the typescript kratos-selfservice-ui-node is documented

There is zero documentation (apart from the auto-generated documentation) for non-typescript kratos-selfservice-ui-node versions. I'm probably overstating this as I only looked at the ruby client library so I can't really comment on the other client libraries! Implementing the self service UI code is not a trivial thing; it's conceptually confusing with all the redirects and two different endpoints. The lack of good examples just makes it even harder. This is also exacerbated by the divergence between the typescript and ruby APIS (see the next point).

The upgrade process

The upgrade from 0.4 to 0.6 has been torturous; there is no other way of putting it. Yes I know it is early days, etc. but the release notes relating to breaking changes (they seem to be automatically generated) make it extremely difficult to actually work out what changes are required from a high level perspective.

Had I known what I know now three days ago I would have started from scratch rather than try to modify the existing code.

I think my code is falling over because the API has completely changed and using the typescript version to work out what I need to do in the ruby version is simply an exercise in futility.

Why do I think the API has completely changed? Because the only example in the README is quite different between version 0.4 and 0.6. Version 0.4 is quite similar to the typescript version whereas the 0.6 version is ... well, to be honest, I'm not really sure what it is.

In the example in the README I have to create an object called OryHydraClient::CreateIdentity add it to a hash where the key is called create_identity and then pass that into a method called create_identity. This is truly the most bizarre API I've ever seen and is as far from the principle of least surprise I think I've ever encountered. I also think this may be reason my code doesn't work but after spending three days working on this I don't want to spend any more time on conjecture.

Converting from the Docker examples to a production environment

Extracting the various configurations from the docker images proved to be a lot trickier that I had expected. I don't use docker (I use LXD) so have no familiarity with it.

I ended up using a combination of the proc filesytem (environment) and general unix tools to extract the configs. I sure there is an easier way but my lack of docker knowledge just makes it hard.

I understand why you put everything in Docker containers but the lack of non-docker configuration examples makes things quite tricky for those of us who don't to/can't use docker.

Possible fix

I think the most of the problems could be fixed by writing a wrapper around the automatically generated library that provides a more idiomatic interface. I don't think it would be too much work and the maintenance burden would be relatively small.

[aeneasr]

Thank you for the feedback, we really appreciated it! I'll try to answer everything in detail below :)

In October last year I wrote a self service UI app in ruby based on the Kratos ruby client library using the official typescript project as a template. I eventually got it working by comparing the wireshark output of the typescript version with my own. It took a while but I put it down to learning a new system. And even though it took me a while to sort it all out it has worked flawlessly since.

Using wireshark to debug definitely sounds a bit frustrating. Do you remember what was the reason for the broken behaviour you experienced?

This is where it where it all starts to get a bit hazy. Nothing worked but I didn't know if the problem was with my kratos setup or with the ruby code. I compared the ruby code with the typescript code and it looks about right so maybe it's the kratos configuration. So I ran up docker-compose and eventually manage to extract a known good kratos configuration file which is virtually identical to the one I have. So kratos looks good. Next I did the same with the kratos-selfservice-ui-node and get that working. But the typescript code is very similar to my ruby code. This is where I start going round and round in circles! So I took a deep breath and started from scratch. I couldn't even get to_session to work, it throws a stack trace seemingly in rack! This turned out to the kratos library trying to log something by iterating over nil.

That also sounds quite frustrating :/ It's of course a good indicator if kratos-selfservice-ui-node works to sanity test if it's a misconfiguration or not!

The API is virtually unusable. I understand why you automatically generate the client code but it is almost unusable: the library documentation is useless and there is one very short example which, at the risk of repeating myself, is virtually useless. I had a look on github to see if anyone else had written something that I could use as an example but there was nothing.

So you mean the Ruby API here, correct? Unfortunately we currently do not have anyone proficient with Ruby. Since we're a small team (I'm actually maintaining Ory Kratos on my own) it is not possible to provide custom SDKs for other languages. Even the Go SDK is auto-generated and I had to create a long PR (still not merged) in OpenAPI Spec to resolve a lot of broken things: OpenAPITools/openapi-generator#8491

For Ruby, there might be a better generator template. I chose the one which looked like it was the default one: https://openapi-generator.tech/docs/generators/ruby/

I'm not sure if another library generator is better or not (e.g. faraday).

The upgrade from 0.4 to 0.6 has been torturous; there is no other way of putting it. Yes I know it is early days, etc. but the release notes relating to breaking changes (they seem to be automatically generated) make it extremely difficult to actually work out what changes are required from a high level perspective.

Yes, v0.6 was a major change in terms of the UI code. I tried to document it as good as possible, update all the respective documentation, but sometimes things can slip. What was the hardest for you here? Was it a lack of description, lack of details, or just the sheer volume of changes? In Ory Hydra I used to write an UPGRADE. At some point I changed the approach and released this high level description as part of the release notes, which you can find here for Ory Kratos 0.6. However, it appears that those are not included in the changelog itself. Did you find these high level release notes? Are you subscribed to the newsletter? We generally include them there. Not including them in the changelog is definitely a bug that we need to resolve. I've created an issue to track that here: #1442

Did you find that page with the release notes? Or is that you're missing? Would it have helped you during upgrading?

Regarding maturity, in our docs we currently state that Ory Kratos is a sandbox project, which has implications on API stability. See Software Maturity. It's still frustrating though. I had an idea to label experimental / alpha APIs as such in the SDKs. What do you think about that? It would make it at least explicit that you're using unstable APIs?

In the example in the README I have to create an object called OryHydraClient::CreateIdentity add it to a hash where the key is called create_identity and then pass that into a method called create_identity. This is truly the most bizarre API I've ever seen and is as far from the principle of least surprise I think I've ever encountered. I also think this may be reason my code doesn't work but after spending three days working on this I don't want to spend any more time on conjecture.

Yeah, I gotta be honest here, with all the love I can give to the maintainers of openapi-generator, most of the generated code is terrible.

I've looked into other options to auto-generate code from OpenAPI but all other options are even worse. The only thing I could find that generates better code is protobuf, but that's an entirely different protocol.

My plan is to beef up our library team and have people dedicated to writing better OpenAPI generator templates for all the different languages. So if you're looking for a job... :)

Extracting the various configurations from the docker images proved to be a lot trickier that I had expected. I don't use docker (I use LXD) so have no familiarity with it.

I ended up using a combination of the proc filesytem (environment) and general unix tools to extract the configs. I sure there is an easier way but my lack of docker knowledge just makes it hard.

I understand why you put everything in Docker containers but the lack of non-docker configuration examples makes things quite tricky for those of us who don't to/can't use docker.

So all Ory software runs with or without Docker. We just ship Docker with Docker Compose because it's easier to boot a database. You can use Ory on raw linux/mac/windows VMs. I'm not sure what difficulties you were facing here? In the simplest case you could SSH into a VM, download the binary, download the config, and go?

I think the most of the problems could be fixed by writing a wrapper around the automatically generated library that provides a more idiomatic interface. I don't think it would be too much work and the maintenance burden would be relatively small.

We have thought about that too. I think a solid approach would be to try and get maintainership and some people dedicated to improving the openapi generator templates so that they match the experience of e.g. the Google SDKs. In the end, the SDKs are still kinda fragile due to the way they are generated (from code docs...) so I'm not sure if writing wrappers wouldn't end up with more work.

---

To follow up with your good feedback, here are some things we had planned before I saw this post, and some which we plan on doing following your post:

1. Include release nodes in the CHANGELOG: Include release notes in CHANGELOG.md #1442
2. Include the changelog in the documentation sidebar so it's easy to find: Include changelog in docs navigation #1443
3. Add more code examples that are actually tested to the documentation - similar to how Stripe is doing it. I've started with this in Golang for the documentation but I think we generally need a test pipeline in the SDK which checks if the code at least compiles: Adopt testing pipeline to see if code compiles and maybe some integration tests sdk#78
4. Hire folks who can help out with improving the openapi generator templates

Do you have any other ideas?

[filterfish]

Thank you for the feedback, we really appreciated it! I'll try to answer everything in detail below :)

Oh good, I was slightly concerned that you take it as a bit of a rant which absolutely wasn't my intention.

In October last year I wrote a self service UI app in ruby based on the Kratos ruby client library using the official typescript project as a template. I eventually got it working by comparing the wireshark output of the typescript version with my own. It took a while but I put it down to learning a new system. And even though it took me a while to sort it all out it has worked flawlessly since.

Using wireshark to debug definitely sounds a bit frustrating. Do you remember what was the reason for the broken behaviour you experienced?

From memory, I didn't want to use docker so I decided to set kratos/oathkeeper up from scratch and was getting confused by the various cominations of flows, ports, apis (public or admin) & hostnames. So I used wireshark to work out what was actually going on and to learn how it all works together.

But I think the underlying reason is the combinatorial explosion of options was just too much, particularly as Ory was new to me then. I didn't have a mental model so I found myself changing values without really understanding the consequences.

This was made worse when Chromium (I use Chromium for development) would often (I can't remember if it was all the time) redirect me to firefox which is my default browser. This alone was driving me absolutely batshit so I just used curl and wireshark. I assume the redirection was because of incorrect config but that's just a guess.

I actually think better documentation—and by this I mean kratos & oathkeeper, not the client libraries—would help a lot here. Just to clarify I think your documentation is really good, especially for such a young project, but there's something that's not quite right. I've been trying to think what it is but I'm not sure I can identify one single thing! The only thing I can think of is that maybe the documentation is too sprawling so I end up with lots of browser tabs open and then I get confused swapping between them. I know that's a bit nebulous but I'll think about it a bit more and see if I can come up with something better.

Maybe a better way of putting it is that all the information is there but it's too spread out.

This is where it where it all starts to get a bit hazy. Nothing worked but I didn't know if the problem was with my kratos setup or with the ruby code. I compared the ruby code with the typescript code and it looks about right so maybe it's the kratos configuration. So I ran up docker-compose and eventually manage to extract a known good kratos configuration file which is virtually identical to the one I have. So kratos looks good. Next I did the same with the kratos-selfservice-ui-node and get that working. But the typescript code is very similar to my ruby code. This is where I start going round and round in circles! So I took a deep breath and started from scratch. I couldn't even get to_session to work, it throws a stack trace seemingly in rack! This turned out to the kratos library trying to log something by iterating over nil.

That also sounds quite frustrating :/ It's of course a good indicator if kratos-selfservice-ui-node works to sanity test if it's a misconfiguration or not!

Yeah, intensely! I've taken a break because I was becoming so aggravated (this says more about me than anything else!) and I'm still not sure how to proceed. As I mentioned I suspect the change in the ruby API is the root cause so I will spend a bit more time trying to get it working before I give up and just use the Org typescript UI app.

The API is virtually unusable. I understand why you automatically generate the client code but it is almost unusable: the library documentation is useless and there is one very short example which, at the risk of repeating myself, is virtually useless. I had a look on github to see if anyone else had written something that I could use as an example but there was nothing.

So you mean the Ruby API here, correct?

Yeah, sorry, I did mean the ruby API.

Unfortunately we currently do not have anyone proficient with Ruby. Since we're a small team (I'm actually maintaining Ory Kratos on my own) it is not possible to provide custom SDKs for other languages. Even the Go SDK is auto-generated and I had to create a long PR (still not merged) in OpenAPI Spec to resolve a lot of broken things: OpenAPITools/openapi-generator#8491

Yeah this is a difficult one. On one hand it's just you maintaining kratos (please be careful crossing the road ;-) so using something like openapi makes a great deal of sense, on the other hand most of the client problems seem to stem from the openapi generated code.

I guess the real question is what does OpenAPI give you?

I've just had a look at the ruby code (admittedly this is only one library) and there is vast amounts of repetition. For example

Command	Line count
grep -Ev '^ +#' api/admin_api.rb | sort -u | wc -l	198
grep -Ev '^ +#' api/admin_api.rb | wc -l	772

So admin_api.rb contains 574 repeated lines and of the remaining 198 lines 34 are log statements, 68 lines are wrapper methods leaving less than a hundred lines of code. I understand that the models might be useful but again the vast majority is duplicate code. If you diff any two models in the models directory the helper methods at the end of each file are exactly the same. Is there a way of having OpenAPI generate relevant code, such as the attribute_map and the openapi_types for each model, and then some hand written code use the generated code?

For Ruby, there might be a better generator template. I chose the one which looked like it was the default one: https://openapi-generator.tech/docs/generators/ruby/

I'm not sure if another library generator is better or not (e.g. faraday).

I've always had a bit of an aversion to code generators so I don't keep well informed however openapi does seem to be the one that I keep seeing. In fact it's the only one I know of. Oh, and faraday is just an http client in the same way the typhoeus is.

The upgrade from 0.4 to 0.6 has been torturous; there is no other way of putting it. Yes I know it is early days, etc. but the release notes relating to breaking changes (they seem to be automatically generated) make it extremely difficult to actually work out what changes are required from a high level perspective.

Yes, v0.6 was a major change in terms of the UI code. I tried to document it as good as possible, update all the respective documentation, but sometimes things can slip. What was the hardest for you here? Was it a lack of description, lack of details, or just the sheer volume of changes? In Ory Hydra I used to write an UPGRADE.

I actually think it's a combination of all three and an UPGRADE document would have been immensely helpful. But I think the biggest of the three was, as you said, the sheer volume; it's hard to keep the salient points in mind when working through it.

At some point I changed the approach and released this high level description as part of the release notes, which you can find here for Ory Kratos 0.6. However, it appears that those are not included in the changelog itself. Did you find these high level release notes? Are you subscribed to the newsletter? We generally include them there. Not including them in the changelog is definitely a bug that we need to resolve. I've created an issue to track that here: #1442

Did you find that page with the release notes? Or is that you're missing? Would it have helped you during upgrading?

I did find the release notes and I went through them fairly carefully, particularly the Breaking Changes section. However I found the Breaking Changes section quite difficult to read as there is lots of repetition. I am also dyslexic so others might find them easier to read.

Regarding maturity, in our docs we currently state that Ory Kratos is a sandbox project, which has implications on API stability. See Software Maturity. It's still frustrating though. I had an idea to label experimental / alpha APIs as such in the SDKs. What do you think about that? It would make it at least explicit that you're using unstable APIs?

I know how hard it is to write good docs, and keep everything in sync and as I mentioned previously I think the docs are pretty good.

In the example in the README I have to create an object called OryHydraClient::CreateIdentity add it to a hash where the key is called create_identity and then pass that into a method called create_identity. This is truly the most bizarre API I've ever seen and is as far from the principle of least surprise I think I've ever encountered. I also think this may be reason my code doesn't work but after spending three days working on this I don't want to spend any more time on conjecture.

Yeah, I gotta be honest here, with all the love I can give to the maintainers of openapi-generator, most of the generated code is terrible.

;-)

I've looked into other options to auto-generate code from OpenAPI but all other options are even worse. The only thing I could find that generates better code is protobuf, but that's an entirely different protocol.

My plan is to beef up our library team and have people dedicated to writing better OpenAPI generator templates for all the different languages. So if you're looking for a job... :)

I am interested but I'm already spreading myself too thinly!

Extracting the various configurations from the docker images proved to be a lot trickier that I had expected. I don't use docker (I use LXD) so have no familiarity with it.
I ended up using a combination of the proc filesytem (environment) and general unix tools to extract the configs. I sure there is an easier way but my lack of docker knowledge just makes it hard.
I understand why you put everything in Docker containers but the lack of non-docker configuration examples makes things quite tricky for those of us who don't to/can't use docker.

So all Ory software runs with or without Docker. We just ship Docker with Docker Compose because it's easier to boot a database. You can use Ory on raw linux/mac/windows VMs. I'm not sure what difficulties you were facing here? In the simplest case you could SSH into a VM, download the binary, download the config, and go?

Yeah, I've been using Ory without docker and I understand why you use docker but the images are quite opaque especially if you don't know docker. ssh isn't running in any of the containers by the way.

As an example these are some of the commands I used (some of these are me just being paranoid). I guess most of these are self explanatory apart from maybe the third point which returns the environment of the running kratos process:

docker exec <container id>  /bin/sh -c "/bin/cat /etc/config/kratos/identity.schema.json" | sed 's/^M//g' > identity.traits.schema.json

docker exec <container id>  /bin/sh -c "/bin/cat /etc/config/kratos/kratos.yml" | sed 's/^M//g' > kratos.yml

docker exec <container id>  /bin/sh -c "/bin/cat /proc/1/environ" | xargs -0 -n1

docker exec <container id>  -c "/bin/cat .git/HEAD"

I think the most of the problems could be fixed by writing a wrapper around the automatically generated library that provides a more idiomatic interface. I don't think it would be too much work and the maintenance burden would be relatively small.

We have thought about that too. I think a solid approach would be to try and get maintainership and some people dedicated to improving the openapi generator templates so that they match the experience of e.g. the Google SDKs. In the end, the SDKs are still kinda fragile due to the way they are generated (from code docs...) so I'm not sure if writing wrappers wouldn't end up with more work.

I guess the key point here is "more work". Given the generated code is fragile (to some degree) and if you have a thousand people using it that effort is a thousand times more than if someone writes a wrapper with a stable interface. Obviously that's a ridiculously naive analysis but you see my point. The counterargument is that you have limited resources so writing a wrapper means you have less time to work on other stuff. I suspect using openapi is ok for now but maybe in the future a hand written library or a wrapper would be a better approach.

That said, how often does, for example, the kratos API actually change? Also as you approach a higher level of maturity surely it will change even less.

In defence of you using openapi, one of the reasons I chose Ory was because it had a client library in a language that I use (my main language is haskell but I've used ruby for over a decade so it tends to be my fallback language) and therefore implementation would be quicker. The irony, however, is that I'll obviously never know if it was quicker :-)

To follow up with your good feedback, here are some things we had planned before I saw this post, and some which we plan on doing following your post:

1. [ ]  Include release nodes in the CHANGELOG: #1442

2. [ ]  Include the changelog in the documentation sidebar so it's easy to find: #1443

3. [ ]  Add more code examples that are actually tested to the documentation - similar to how Stripe is doing it. I've started with this [in Golang](https://github.com/ory/kratos/tree/master/examples/go/init) for the documentation but I think we generally need a test pipeline in the SDK which checks if the code at least compiles: [ory/sdk#78](https://github.com/ory/sdk/issues/78)

4. [ ]  Hire folks who can help out with improving the openapi generator templates

Do you have any other ideas?

I would add to this list:

• An UPGRADE document (which you alluded to in a previous comment)
• A high level summary of any changes
• Better document about integrating the various Ory components.

The last point is slightly tangential to the main overall points but it significantly increases the cognitive load when using them together.