Use the examples directory for example plugin code

[ptgott]

Closes #27696

Also edit the Access Request plugin API guide to use this directory, rather than having the reader copy/paste individual code snippets. This makes the guide easier to follow, and users will have a compilable example before they proceed through the guide.

See this discussion for context. I will also apply similar changes to my in-progress API guides.

[alexfornuto]

I'm not a go programmer so I don't know if this makes sense, but if the sections that we break out and describe individually in these guides could be separate files imported into a main file, we could use partials inside the code blocks and ensure that the docs remain up-to-date if/when the examples change.

[ptgott]

@alexfornuto I think that's a really good idea, though it will result in a slightly strange-looking program, since we'll have a collection of very small .go files. What do you think, @zmb3 ?

Edit: another aspect of this is that we would need to include package main at the top of each partial, which will also look strange within the guide itself.

[Joerger]

This is an awesome guide and sample project!

I'm not a go programmer so I don't know if this makes sense, but if the sections that we break out and describe individually in these guides could be separate files imported into a main file, we could use partials inside the code blocks and ensure that the docs remain up-to-date if/when the examples change.

+1 to this idea. I wouldn't split it into 10 files or anything, but I think you could reasonbly chunk it like this or similar:

• func main
• run and handleEvent
• updateSpreadsheet
• updateRow and createRow
• makeRowData

... another aspect of this is that we would need to include package main at the top of each partial, which will also look strange within the guide itself.

IMO overall it's a worthwhile tradeoff, and as a Go programmer I wouldn't be confused by it.

[Joerger]

nit: From the perspective of using this example as a base for one's own custom plugin, it would be cool to make the code a bit more modular. For example, rather than having a googleSheetsPlugin, we could have something like:

type accessRequestPlugin struct {
	teleportClient *client.Client
        eventHandler interface {
                HandleEvent(ctx context.Context, event types.Event) error
        }
}

type googleSheetsClient struct {
        sheetsClient   *sheets.SpreadsheetsService
}

func (*googleSheetsClient) HandleEvent(ctx context.Context, event types.Event) error {
       ...
}

plugin := accessRequestPlugin{
       teleportClient: ...,
       eventHandler: googleSheetsClient{
              sheetsClient: ...,
       }
}

Then the user could just swap out eventHandler with their own implementation very intuitively. This would also make splitting the code into separate files more natural.

I think this PR is a big improvement regardless, so this is more of a follow up suggestion than a blocker.

[ptgott]

This sounds great, especially if we want to make it the recommended way for a user to build/test their own Access Request plugin. If this is the way we want to go, I can look into making this change.

When writing this guide, though, I had imagined the example as something that would demonstrate some key libraries in a runnable way, but not the basis for an actual production plugin. Is there anything else we'd need to add to the accessRequestPlugin type to make it more generally usable?

[Joerger]

Nothing off the top of my head, just having a teleport Client and some customizable event handler seems sufficient as a base.

[ptgott]

Going to put this one in draft and plan to rework the example application so it doesn't rely on watcherjob. Instead, we can use teleport/api/types.Events.

[ptgott]

@Joerger I've finished incorporating your feedback by declaring the types you suggested! I've also added changes to address #27696 by eschewing the watcherjob package for types from the api package.

[alexfornuto]

Copy changes look good, with one nit.

[ptgott]

@zmb3 Friendly ping to see if I resolved your feedback

[public-teleport-github-review-bot]

@ptgott See the table below for backport results.

Branch	Result
branch/v11	Create PR
branch/v12	Create PR
branch/v13	Create PR