Register an api description without handler

[clintjedwards]

Hello!

I'm not sure if this is possible, but I figured I would ask. I'm attempting to transition a GRPC API into using REST. So far Huma is making that really easy to get good documentation and a spec out of the migration. I'm loving it so far, thank you.

One feature of GRPC I've run into that is causing me issues is the ability to have a bi-directional stream with a client. To solve this I've picked up websockets, but (to my knowledge) all websockets tooling expects access to the underlying http.ResponseWriter and http.Request objects such that it may manage the request writes and reads.

I searched a bit, but it does not seem like Huma gives this access to these objects, so I figured no big deal, I'll just add the handler manually to my router. But if I do that then I don't get the great autogenerated openapi spec from huma for that specific route.

I also tried adding an empty handler func via huma.Register to get the documentation and then added (at the end) a router.HandleFunc with the same path I gave the register command to see if I could overwrite the handler. This didn't work and weirdly enough no matter which position the default router handler was in put in, the huma handler was run instead.

I was wondering if there is a way to do one of two things:

1. Register a route without a handler so that I may register the handler through the native router API.
2. Overwrite the current handler for a particular route (I'll be honest that I was too lazy to look deeper into this part, but I assume that huma just adds on to the default router's route table)

Or anything else that might help on this front. I'd also be willing to help with a PR if you have a feature in mind you just don't have the time for.

Thanks!

[bclements]

Wouldn’t you want to do this using SSE instead of webhooks? I may be misunderstanding your use case.

…

On Tue, Apr 9, 2024 at 3:38 PM Clint J. Edwards ***@***.***> wrote: Hello! I'm not sure if this is possible, but I figured I would ask. I'm attempting to transition a GRPC API into using REST and so far Huma is making that really easy to get good documentation and a spec out of the migration. I'm loving it so far, thank you. One feature of GRPC I've run into that is causing me issues is the ability to have a bi-directional stream with a client. To solve this I've picked up webhooks, but (to my knowledge) all webhook tooling expects access to the underlying http.ResponseWriter and http.Request objects such that it may manage the request writes and reads. I searched a bit, but it does not seem like Huma give this access to these objects, so I figured no big deal, I'll just add the handler manually to my router. But if I do that then I don't get the great autogenerated openapi spec from huma for that specific route. I also tried adding an empty huma.Operation func via huma.Register to get the documentation and then added (at the end) a router.HandleFunc with the same path I gave the register command to see if I could overwrite the handler. This didn't work and weirdly enough no matter which position the default router handler was in put in, the huma handler was run instead. I was wondering if there is a way to do one of two things: 1. Register a route without a handler so that I may register the handler through the native router API. 2. Overwrite the current handler for a particular route (I'll be honest that I was too lazy to look deeper into this part, but I assume that huma just adds on to the default router's route table) Or anything else that might help on this front. I'd also be willing to help with a PR if you have a feature in mind you just don't have the time for. Thanks! — Reply to this email directly, view it on GitHub <#366>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5CHXPXZ3P4S3IZ5ZVD2LTY4RUVTAVCNFSM6AAAAABF7ML66KVHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZWGQ4DIOBRGU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[clintjedwards]

My understanding is that SSE is unidirectional, I'm setting up webhooks because ideally I'd like the server to push some events, then the client, then server, and so on.

[bclements]

Correct then you’d be looking at websockets not webhooks.

…

On Tue, Apr 9, 2024 at 8:20 PM Clint J. Edwards ***@***.***> wrote: My understanding is that SSE is unidirectional, I'm setting up webhooks because ideally I'd like the server to push some events, then the client, then server, and so on. — Reply to this email directly, view it on GitHub <#366 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5CHXKV7LCDCSHQAGNQL2LY4SVZLAVCNFSM6AAAAABF7ML66KVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TANRVHAYTM> . You are receiving this because you commented.Message ID: ***@***.***>

[bclements]

I am idiot, I assume this is for service to service communication so webhooks is appropriate. I will go back to lurking now. :) On Wed, Apr 10, 2024 at 1:46 AM Brent Clements ***@***.***> wrote:

…

Correct then you’d be looking at websockets not webhooks. On Tue, Apr 9, 2024 at 8:20 PM Clint J. Edwards ***@***.***> wrote: > My understanding is that SSE is unidirectional, I'm setting up webhooks > because ideally I'd like the server to push some events, then the client, > then server, and so on. > > — > Reply to this email directly, view it on GitHub > <#366 (reply in thread)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AA5CHXKV7LCDCSHQAGNQL2LY4SVZLAVCNFSM6AAAAABF7ML66KVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TANRVHAYTM> > . > You are receiving this because you commented.Message ID: > ***@***.***> >

[clintjedwards]

No @bclements, actually you're completely correct. I am the idiot. I typed this after searching for a solution for several hours so I assume I was just tired, but I actually meant websockets not webhooks. I'm not sure why my brain typed webhooks several times.

I've edited the original post to actually say websockets now. Sorry for the confusion.

Thanks for the gut check.

[bclements]

Webhooks can also be used for service to service communication but limited use cases. So you technically weren't wrong.

…

On Wed, Apr 10, 2024 at 9:28 AM Clint J. Edwards ***@***.***> wrote: No @bclements <https://github.com/bclements>, actually you're completely correct. I am the idiot. I typed this after searching for a solution for several hours so I assume I was just tired, but I actually meant websockets not webhooks. I'm not sure why my brain typed webhooks several times. — Reply to this email directly, view it on GitHub <#366 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5CHXITZV7APY4SWT4JCIDY4VSDFAVCNFSM6AAAAABF7ML66KVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TANZTGY3TM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[danielgtaylor]

@clintjedwards you have full access to the OpenAPI so can modify it as needed. Here's a quick runnable example: https://go.dev/play/p/GGkYMi3Cn26

api.OpenAPI().Paths["/demo"] = &huma.PathItem{
	Get: &huma.Operation{
		OperationID: "get-demo",
		Summary:     "Get a demo",
		Responses: map[string]*huma.Response{
			"200": {
				Description: "OK",
				Content: map[string]*huma.MediaType{
					"application/json": {
						Schema: &huma.Schema{Type: huma.TypeString},
					},
				},
			},
		},
	},
}

It's a little extra work, but you can manually describe any operation registered with the underlying router that way. You can also use the schema registry at api.OpenAPI().Components.Schemas to get schemas for your types to put into the OpenAPI, including generating $refs as needed. Hope this helps!

[clintjedwards]

Oh man it seems so obvious now in retrospect. Many thanks, sorry for the simple question.

[davidolrik]

@danielgtaylor The way you are adding them here assumes that you have previously added another endpoint, if you haven't you'll get a panic: assignment to entry in nil map

The correct or preferred way to do it would be via AddOperation() like so:

api.OpenAPI().AddOperation(
	&huma.Operation{
		OperationID: "get-demo",
		Method: http.MethodGet,
		Path: "/demo",
		Summary: "Get a demo",
		Responses: map[string]*huma.Response{
			"200": {
				Description: "OK",
				Content: map[string]*huma.MediaType{
					"application/json": {
						Schema: &huma.Schema{Type: huma.TypeString},
					},
				},
			},
		},
	},
)

I got bitten by random panics as I had previously done as you suggested above.

Because the load order of my handlers are non deterministic, sometimes the one with the direct access to api.OpenAPI().Paths["..."] would get called first resulting in a panic.