feat(Coder plugin): expose Coder SDK to Backstage end-users

Parkreiner commented 3 months ago

Part of #112

Changes made

Created useCoderQuery hook that simplifies wiring up all the Coder plugin logic to useQuery
Added an initial set of tests for the hook
Gave users the ability to disable the auth fallback UI altogether
Updated some of the test helpers

Example usage

This is from the end-user's perspective (useEndUserCoderAuth will already have been renamed to just useCoderAuth)

// Without useCoderQuery
const { sdk } = useCoderSdk();
const { isAuthenticated } = useCoderAuth();
const query = useQuery({
  queryKey: [CODER_QUERY_KEY_PREFIX, "workspaces"],
  queryFn: () => sdk.getWorkspaces({ q: "owner:me" }),
  enabled: isAuthenticated,
});

// This is fully equivalent and has additional properties get updated based on auth status
const query2 = useCoderQuery({
  queryKey: ["workspaces"],
  queryFn: ({ sdk }) => sdk.getWorkspaces({ q: "owner:me" })
});

Notes

I originally wanted to create a useCoderMutation hook, too, but decided to put it on the back-burner for now because:
- I fully expect queries to be the way that users interact with the API +75% of the time
- On Thursday, I'm going to start working on the Windows RDP module, and I knew I wouldn't have time to get both hooks ready and tested (need to test them individually and together)
- We still need some idea of what flows devs are going to be using with these hooks, so best not to commit to some false assumptions until we have more concrete user data
Will publish a new PR with documentation changes soon

code-asher commented 3 months ago

Oh yeah wait the whole reason is to make it Backstage-y with the useApi stuff. Yeah gotta be the way you have it, I think.

Parkreiner commented 3 months ago

@code-asher Yeah, I tried to improve the co-location for the auth/SDK stuff to make their relationship a little more obvious, but when I tried it, I think the changes made things more confusing. I tried adding some auth-based helpers to useCoderSdk, but then it felt like that was blurring some of the lines for the responsibilities for it and useCoderAuth

I agree that the SDK setup flow you posted would be nice, but I don't know how to make that play nicely with React and Backstage. We don't have to do things the Backstage way – we could make it so that the user has to initialize the Coder Client themselves (making sure it's initialized outside a render function), and then feed that to the rest of the app via React Context. That's not the Backstage way, but it is the React way, which is good enough for me

The main thing I'm not 100% sure on is that, with the client being dependent on other Backstage APIs, you might have to jump through a ton of hoops to get feed those into the Coder Client since you lose access to API factories. It should be doable, but I'm not 100% sure if that might add more confusion, or might make the code even more complex

Parkreiner commented 3 months ago

@code-asher Yeah, this is definitely one area where I wish we had more active users to get feedback from. I definitely don't expect this to be the final design, but it feels like exposing the Coder API at all is going to a good way to entice people to try out the plugin, and get the feedback on how to make this better

I just wish that, for a platform built with React, Backstage were integrated with it a little bit better. The fact that we have to weigh the tradeoffs between React-isms and Backstage-isms doesn't feel super great

code-asher commented 3 months ago

I just wish that, for a platform built with React, Backstage were integrated with it a little bit better. The fact that we have to weigh the tradeoffs between React-isms and Backstage-isms doesn't feel super great

This 100%, could not agree more!!

coder / backstage-plugins