[pbs-devel] [pve-devel] [PATCH manager v2 07/12] api: add routes for webhook notification endpoints

[Max Carrara]

On Mon Jul 22, 2024 at 9:37 AM CEST, Lukas Wagner wrote:
>
>
> On  2024-07-17 17:36, Max Carrara wrote:
> > On Fri Jul 12, 2024 at 1:27 PM CEST, Lukas Wagner wrote:
> >> These just call the API implementation via the perl-rs bindings.
> >>
> >> Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
> >> ---
> >>  PVE/API2/Cluster/Notifications.pm | 263 +++++++++++++++++++++++++++++-
> >>  1 file changed, 262 insertions(+), 1 deletion(-)
> >>
> >> diff --git a/PVE/API2/Cluster/Notifications.pm b/PVE/API2/Cluster/Notifications.pm
> >> index 10b611c9..eae2d436 100644
> >> --- a/PVE/API2/Cluster/Notifications.pm
> >> +++ b/PVE/API2/Cluster/Notifications.pm
> >> @@ -108,6 +108,7 @@ __PACKAGE__->register_method ({
> >>  	    { name => 'gotify' },
> >>  	    { name => 'sendmail' },
> >>  	    { name => 'smtp' },
> >> +	    { name => 'webhook' },
> >>  	];
> >>  
> >>  	return $result;
> >> @@ -144,7 +145,7 @@ __PACKAGE__->register_method ({
> >>  		'type' => {
> >>  		    description => 'Type of the target.',
> >>  		    type  => 'string',
> >> -		    enum => [qw(sendmail gotify smtp)],
> >> +		    enum => [qw(sendmail gotify smtp webhook)],
> >>  		},
> >>  		'comment' => {
> >>  		    description => 'Comment',
> >> @@ -1094,6 +1095,266 @@ __PACKAGE__->register_method ({
> >>      }
> >>  });
> >>  
> >> +my $webhook_properties = {
> >> +    name => {
> >> +	description => 'The name of the endpoint.',
> >> +	type => 'string',
> >> +	format => 'pve-configid',
> >> +    },
> >> +    url => {
> >> +	description => 'Server URL',
> >> +	type => 'string',
> >> +    },
> >> +    method => {
> >> +	description => 'HTTP method',
> >> +	type => 'string',
> >> +	enum => [qw(post put get)],
> >> +    },
> >> +    header => {
> >> +	description => 'HTTP headers to set. These have to be formatted as'
> >> +	  . ' a property string in the format name=<name>,value=<base64 of value>',
> >> +	type => 'array',
> >> +	items => {
> >> +	    type => 'string',
> >> +	},
> >> +	optional => 1,
> >> +    },
> >> +    body => {
> >> +	description => 'HTTP body, base64 encoded',
> >> +	type => 'string',
> >> +	optional => 1,
> >> +    },
> >> +    secret => {
> >> +	description => 'Secrets to set. These have to be formatted as'
> >> +	  . ' a property string in the format name=<name>,value=<base64 of value>',
> >> +	type => 'array',
> >> +	items => {
> >> +	    type => 'string',
> >> +	},
> >> +	optional => 1,
> >> +    },
> >> +    comment => {
> >> +	description => 'Comment',
> >> +	type => 'string',
> >> +	optional => 1,
> >> +    },
> >> +    disable => {
> >> +	description => 'Disable this target',
> >> +	type => 'boolean',
> >> +	optional => 1,
> >> +	default => 0,
> >> +    },
> >> +};
> >> +
> >> +__PACKAGE__->register_method ({
> >> +    name => 'get_webhook_endpoints',
> >> +    path => 'endpoints/webhook',
> >> +    method => 'GET',
> >> +    description => 'Returns a list of all webhook endpoints',
> >> +    protected => 1,
> >> +    permissions => {
> >> +	check => ['perm', '/mapping/notifications', ['Mapping.Modify']],
> >> +	check => ['perm', '/mapping/notifications', ['Mapping.Audit']],
> >> +    },
> >> +    parameters => {
> >> +	additionalProperties => 0,
> >> +	properties => {},
> >> +    },
> >> +    returns => {
> >> +	type => 'array',
> >> +	items => {
> >> +	    type => 'object',
> >> +	    properties => {
> >> +		%$webhook_properties,
> > 
> > Would prefer `$webhook_properties->%*` here (postfix dereferencing) -
> > even though not explicitly stated in our style guide, we use that kind
> > of syntax for calling subroutines behind a reference, e.g.
> > `$foo->($arg)` instead of `&$foo($arg)`.
> > 
>
> I kinda prefer the brevity of the prefix variant in this case. Are there
> any pitfalls/problems with the prefix that I'm not aware of? If not, I'd prefer
> to keep this as is, I used the syntax in many other spots in this file ;)

I personally have no hard feelings if you keep it tbh. Postfix
dereference is mainly useful if you have e.g. a nested hash (or rather,
makes more sense) because of how the code is usually read. For example,

    %$foo->{bar}->{baz}

vs

    $foo->{bar}->{baz}->%*

I'd argue that the main benefit is that it's easier to read for people
who aren't as familiar with Perl, but before this gets too bikesheddy,
I'm personally fine if you keep it as-is for simple cases like the above
:P