From 5169feb6de96e0b5400ee0476f797dc7ee6a6aa0 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 14:47:40 +0200 Subject: [PATCH 01/12] Mark all API methods as deprecated --- script/zonemaster_backend_rpcapi.psgi | 28 ++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/script/zonemaster_backend_rpcapi.psgi b/script/zonemaster_backend_rpcapi.psgi index b4dd72eea..2d4859406 100644 --- a/script/zonemaster_backend_rpcapi.psgi +++ b/script/zonemaster_backend_rpcapi.psgi @@ -59,56 +59,68 @@ my $handler = Zonemaster::Backend::RPCAPI->new( { config => $config } ); my $router = router { ############## FRONTEND #################### + # Deprecated connect "version_info" => { handler => $handler, action => "version_info" }; + + # Deprecated connect "profile_names" => { - handler => $handler, - action => "profile_names" - }; + handler => $handler, + action => "profile_names" + }; + # Deprecated connect "get_language_tags" => { - handler => $handler, - action => "get_language_tags" - }; + handler => $handler, + action => "get_language_tags" + }; - connect "get_host_by_name" => { + # Deprecated + connect "get_host_by_name" => { handler => $handler, action => "get_host_by_name" }; + # Deprecated connect "get_data_from_parent_zone" => { handler => $handler, action => "get_data_from_parent_zone" }; + # Deprecated connect "start_domain_test" => { handler => $handler, action => "start_domain_test" }; + # Deprecated connect "test_progress" => { handler => $handler, action => "test_progress" }; + # Deprecated connect "get_test_params" => { handler => $handler, action => "get_test_params" }; + # Deprecated connect "get_test_results" => { handler => $handler, action => "get_test_results" }; + # Deprecated connect "get_test_history" => { handler => $handler, action => "get_test_history" }; + # Deprecated connect "get_batch_job_result" => { handler => $handler, action => "get_batch_job_result" @@ -117,6 +129,7 @@ my $router = router { if ($config->RPCAPI_enable_add_api_user) { $log->info('Enabling add_api_user method'); + #Deprecated $router->connect("add_api_user", { handler => $handler, action => "add_api_user" @@ -125,6 +138,7 @@ if ($config->RPCAPI_enable_add_api_user) { if ($config->RPCAPI_enable_add_batch_job) { $log->info('Enabling add_batch_job method'); + #Deprecated $router->connect("add_batch_job", { handler => $handler, action => "add_batch_job" From 2e8ae15aa23ae4570b9fe12f29504d7f4f5464e2 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 14:53:53 +0200 Subject: [PATCH 02/12] Provide new API methods --- script/zonemaster_backend_rpcapi.psgi | 66 ++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 2 deletions(-) diff --git a/script/zonemaster_backend_rpcapi.psgi b/script/zonemaster_backend_rpcapi.psgi index 2d4859406..f219b51ea 100644 --- a/script/zonemaster_backend_rpcapi.psgi +++ b/script/zonemaster_backend_rpcapi.psgi @@ -65,6 +65,10 @@ my $router = router { action => "version_info" }; + connect "system_versions" => { + handler => $handler, + action => "system_versions" + }; # Deprecated connect "profile_names" => { @@ -72,77 +76,135 @@ my $router = router { action => "profile_names" }; + connect "conf_profiles" => { + handler => $handler, + action => "conf_profiles" + }; + # Deprecated connect "get_language_tags" => { handler => $handler, action => "get_language_tags" }; + connect "conf_languages" => { + handler => $handler, + action => "conf_languages" + }; + # Deprecated connect "get_host_by_name" => { handler => $handler, action => "get_host_by_name" }; + connect "lookup_address_records" => { + handler => $handler, + action => "lookup_address_records" + }; + # Deprecated connect "get_data_from_parent_zone" => { handler => $handler, action => "get_data_from_parent_zone" }; + connect "lookup_delegation_data" => { + handler => $handler, + action => "lookup_delegation_data" + }; + # Deprecated connect "start_domain_test" => { handler => $handler, action => "start_domain_test" }; + connect "job_create" => { + handler => $handler, + action => "job_create" + }; + # Deprecated connect "test_progress" => { handler => $handler, action => "test_progress" }; + connect "job_status" => { + handler => $handler, + action => "job_status" + }; + # Deprecated connect "get_test_params" => { handler => $handler, action => "get_test_params" }; + connect "job_params" => { + handler => $handler, + action => "job_params" + }; + # Deprecated connect "get_test_results" => { handler => $handler, action => "get_test_results" }; + connect "job_results" => { + handler => $handler, + action => "job_results" + }; + # Deprecated connect "get_test_history" => { handler => $handler, action => "get_test_history" }; + connect "domain_history" => { + handler => $handler, + action => "domain_history" + }; + # Deprecated connect "get_batch_job_result" => { handler => $handler, action => "get_batch_job_result" }; + + connect "batch_status" => { + handler => $handler, + action => "batch_status" + }; }; if ($config->RPCAPI_enable_add_api_user) { - $log->info('Enabling add_api_user method'); + $log->info('Enabling user_create method'); #Deprecated $router->connect("add_api_user", { handler => $handler, action => "add_api_user" }); + $router->connect("user_create", { + handler => $handler, + action => "user_create" + }); } if ($config->RPCAPI_enable_add_batch_job) { - $log->info('Enabling add_batch_job method'); + $log->info('Enabling batch_create method'); #Deprecated $router->connect("add_batch_job", { handler => $handler, action => "add_batch_job" }); + $router->connect("batch_create", { + handler => $handler, + action => "batch_create" + }); } my $dispatch = JSON::RPC::Dispatch->new( From cc4d7eba20a080282735ee159e5aec1ccc151eee Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 15:22:01 +0200 Subject: [PATCH 03/12] Duplicate methods with new names And mark old ones as deprecated --- lib/Zonemaster/Backend/RPCAPI.pm | 392 ++++++++++++++++++++++++++++++- 1 file changed, 379 insertions(+), 13 deletions(-) diff --git a/lib/Zonemaster/Backend/RPCAPI.pm b/lib/Zonemaster/Backend/RPCAPI.pm index 9c5ef61ac..756576076 100644 --- a/lib/Zonemaster/Backend/RPCAPI.pm +++ b/lib/Zonemaster/Backend/RPCAPI.pm @@ -101,7 +101,25 @@ sub handle_exception { die $exception->as_hash; } -$json_schemas{version_info} = joi->object->strict; +$json_schemas{system_versions} = joi->object->strict; +sub system_versions { + my ( $self ) = @_; + + my %ver; + eval { + $ver{zonemaster_ldns} = Zonemaster::LDNS->VERSION; + $ver{zonemaster_engine} = Zonemaster::Engine->VERSION; + $ver{zonemaster_backend} = Zonemaster::Backend->VERSION; + }; + if ($@) { + handle_exception( $@ ); + } + + return \%ver; +} + +# Deprecated +$json_schemas{version_info} = $json_schemas{system_versions}; sub version_info { my ( $self ) = @_; @@ -118,7 +136,21 @@ sub version_info { return \%ver; } -$json_schemas{profile_names} = joi->object->strict; +$json_schemas{conf_profiles} = joi->object->strict; +sub conf_profiles { + my ( $self ) = @_; + + my %profiles; + eval { %profiles = $self->{config}->PUBLIC_PROFILES }; + if ( $@ ) { + handle_exception( $@ ); + } + + return [ keys %profiles ]; +} + +# Deprecated +$json_schemas{profile_names} = $json_schemas{conf_profiles}; sub profile_names { my ( $self ) = @_; @@ -133,7 +165,31 @@ sub profile_names { # Return the list of language tags supported by get_test_results(). The tags are # derived from the locale tags set in the configuration file. -$json_schemas{get_language_tags} = joi->object->strict; +$json_schemas{conf_languages} = joi->object->strict; +sub conf_languages { + my ( $self ) = @_; + + my @lang_tags; + eval { + my %locales = $self->{config}->LANGUAGE_locale; + + for my $lang ( sort keys %locales ) { + my @locale_tags = sort keys %{ $locales{$lang} }; + if ( scalar @locale_tags == 1 ) { + push @lang_tags, $lang; + } + push @lang_tags, @locale_tags; + } + }; + if ( $@ ) { + handle_exception( $@ ); + } + + return \@lang_tags; +} + +# Deprecated +$json_schemas{get_language_tags} = $json_schemas{conf_languages}; sub get_language_tags { my ( $self ) = @_; @@ -156,7 +212,7 @@ sub get_language_tags { return \@lang_tags; } -$json_schemas{get_host_by_name} = { +$json_schemas{lookup_address_records} = { type => 'object', additionalProperties => 0, required => [ 'hostname' ], @@ -164,6 +220,26 @@ $json_schemas{get_host_by_name} = { hostname => $zm_validator->domain_name } }; +sub lookup_address_records { + my ( $self, $params ) = @_; + my @adresses; + + eval { + my $ns_name = $params->{hostname}; + + @adresses = map { {$ns_name => $_->short} } $recursor->get_addresses_for($ns_name); + @adresses = { $ns_name => '0.0.0.0' } if not @adresses; + + }; + if ($@) { + handle_exception( $@ ); + } + + return \@adresses; +} + +# Deprecated +$json_schemas{get_host_by_name} = $json_schemas{lookup_address_records}; sub get_host_by_name { my ( $self, $params ) = @_; my @adresses; @@ -182,7 +258,7 @@ sub get_host_by_name { return \@adresses; } -$json_schemas{get_data_from_parent_zone} = { +$json_schemas{lookup_delegation_data} = { type => 'object', additionalProperties => 0, required => [ 'domain' ], @@ -191,6 +267,46 @@ $json_schemas{get_data_from_parent_zone} = { language => $zm_validator->language_tag, } }; +sub lookup_delegation_data { + my ( $self, $params ) = @_; + + my $result = eval { + my %result; + my $domain = $params->{domain}; + + my @ns_list; + my @ns_names; + + my $zone = Zonemaster::Engine->zone( $domain ); + push @ns_list, { ns => $_->name->string, ip => $_->address->short} for @{$zone->glue}; + + my @ds_list; + + $zone = Zonemaster::Engine->zone($domain); + my $ds_p = $zone->parent->query_one( $zone->name, 'DS', { dnssec => 1, cd => 1, recurse => 1 } ); + if ($ds_p) { + my @ds = $ds_p->get_records( 'DS', 'answer' ); + + foreach my $ds ( @ds ) { + next unless $ds->type eq 'DS'; + push(@ds_list, { keytag => $ds->keytag, algorithm => $ds->algorithm, digtype => $ds->digtype, digest => $ds->hexdigest }); + } + } + + $result{ns_list} = \@ns_list; + $result{ds_list} = \@ds_list; + return \%result; + }; + if ($@) { + handle_exception( $@ ); + } + elsif ($result) { + return $result; + } +} + +# Deprecated +$json_schemas{get_data_from_parent_zone} = $json_schemas{lookup_delegation_data}; sub get_data_from_parent_zone { my ( $self, $params ) = @_; @@ -229,7 +345,7 @@ sub get_data_from_parent_zone { } } -$json_schemas{start_domain_test} = { +$json_schemas{job_create} = { type => 'object', additionalProperties => 0, required => [ 'domain' ], @@ -254,6 +370,34 @@ $json_schemas{start_domain_test} = { language => $zm_validator->language_tag, } }; +sub job_create { + my ( $self, $params ) = @_; + + my $result = 0; + eval { + $params->{domain} =~ s/^\.// unless ( !$params->{domain} || $params->{domain} eq '.' ); + + die "No domain in parameters\n" unless ( defined $params->{domain} && length($params->{domain}) ); + + $params->{profile} //= "default"; + $params->{priority} //= 10; + $params->{queue} //= 0; + + my $profile = $self->{_profiles}{ $params->{profile} }; + $params->{ipv4} //= $profile->get( "net.ipv4" ); + $params->{ipv6} //= $profile->get( "net.ipv6" ); + + $result = $self->{db}->create_new_test( $params->{domain}, $params, $self->{config}->ZONEMASTER_age_reuse_previous_test ); + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{start_domain_test} = $json_schemas{job_create}; sub start_domain_test { my ( $self, $params ) = @_; @@ -280,9 +424,26 @@ sub start_domain_test { return $result; } -$json_schemas{test_progress} = joi->object->strict->props( +$json_schemas{job_status} = joi->object->strict->props( test_id => $zm_validator->test_id->required ); +sub job_status { + my ( $self, $params ) = @_; + + my $result = 0; + eval { + my $test_id = $params->{test_id}; + $result = $self->{db}->test_progress( $test_id ); + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{test_progress} = $json_schemas{job_create}; sub test_progress { my ( $self, $params ) = @_; @@ -298,9 +459,27 @@ sub test_progress { return $result; } -$json_schemas{get_test_params} = joi->object->strict->props( +$json_schemas{job_params} = joi->object->strict->props( test_id => $zm_validator->test_id->required ); +sub job_params { + my ( $self, $params ) = @_; + + my $result; + eval { + my $test_id = $params->{test_id}; + + $result = $self->{db}->get_test_params( $test_id ); + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{get_test_params} = $json_schemas{job_params}; sub get_test_params { my ( $self, $params ) = @_; @@ -317,7 +496,7 @@ sub get_test_params { return $result; } -$json_schemas{get_test_results} = { +$json_schemas{job_results} = { type => 'object', additionalProperties => 0, required => [ 'id', 'language' ], @@ -326,6 +505,94 @@ $json_schemas{get_test_results} = { language => $zm_validator->language_tag, } }; +sub job_results { + my ( $self, $params ) = @_; + + my $result; + eval{ + + my $locale = $self->_get_locale( $params ); + + my $translator; + $translator = Zonemaster::Backend::Translator->new; + + my $previous_locale = $translator->locale; + if ( !$translator->locale( $locale ) ) { + die "Failed to set locale: $locale"; + } + + eval { $translator->data } if $translator; # Provoke lazy loading of translation data + + my @zm_results; + my %testcases; + + my $test_info = $self->{db}->test_results( $params->{id} ); + foreach my $test_res ( @{ $test_info->{results} } ) { + my $res; + if ( $test_res->{module} eq 'NAMESERVER' ) { + $res->{ns} = ( $test_res->{args}->{ns} ) ? ( $test_res->{args}->{ns} ) : ( 'All' ); + } + elsif ($test_res->{module} eq 'SYSTEM' + && $test_res->{tag} eq 'POLICY_DISABLED' + && $test_res->{args}->{name} eq 'Example' ) + { + next; + } + + $res->{module} = $test_res->{module}; + $res->{message} = $translator->translate_tag( $test_res ) . "\n"; + $res->{message} =~ s/,/, /isg; + $res->{message} =~ s/;/; /isg; + $res->{level} = $test_res->{level}; + $res->{testcase} = $test_res->{testcase} // 'UNSPECIFIED'; + $testcases{$res->{testcase}} = $translator->test_case_description($res->{testcase}); + + if ( $test_res->{module} eq 'SYSTEM' ) { + if ( $res->{message} =~ /policy\.json/ ) { + my ( $policy ) = ( $res->{message} =~ /\s(\/.*)$/ ); + if ( $policy ) { + my $policy_description = 'DEFAULT POLICY'; + $policy_description = 'SOME OTHER POLICY' if ( $policy =~ /some\/other\/policy\/path/ ); + $res->{message} =~ s/$policy/$policy_description/; + } + else { + $res->{message} = 'UNKNOWN POLICY FORMAT'; + } + } + elsif ( $res->{message} =~ /config\.json/ ) { + my ( $config ) = ( $res->{message} =~ /\s(\/.*)$/ ); + if ( $config ) { + my $config_description = 'DEFAULT CONFIGURATION'; + $config_description = 'SOME OTHER CONFIGURATION' if ( $config =~ /some\/other\/configuration\/path/ ); + $res->{message} =~ s/$config/$config_description/; + } + else { + $res->{message} = 'UNKNOWN CONFIG FORMAT'; + } + } + } + + push( @zm_results, $res ); + } + + $result = $test_info; + $result->{testcase_descriptions} = \%testcases; + $result->{results} = \@zm_results; + + $translator->locale( $previous_locale ); + + $result = $test_info; + $result->{results} = \@zm_results; + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{get_test_results} = $json_schemas{job_results}; sub get_test_results { my ( $self, $params ) = @_; @@ -412,7 +679,7 @@ sub get_test_results { return $result; } -$json_schemas{get_test_history} = { +$json_schemas{domain_history} = { type => 'object', additionalProperties => 0, required => [ 'frontend_params' ], @@ -430,6 +697,30 @@ $json_schemas{get_test_history} = { } } }; +sub domain_history { + my ( $self, $params ) = @_; + + my $results; + + eval { + $params->{offset} //= 0; + $params->{limit} //= 200; + $params->{filter} //= "all"; + + $results = $self->{db}->get_test_history( $params ); + my @results = map { { %$_, undelegated => $_->{undelegated} ? JSON::PP::true : JSON::PP::false } } @$results; + $results = \@results; + + }; + if ($@) { + handle_exception( $@ ); + } + + return $results; +} + +# Deprecated +$json_schemas{get_test_history} = $json_schemas{domain_history}; sub get_test_history { my ( $self, $params ) = @_; @@ -452,10 +743,43 @@ sub get_test_history { return $results; } -$json_schemas{add_api_user} = joi->object->strict->props( +$json_schemas{user_create} = joi->object->strict->props( username => $zm_validator->username->required, api_key => $zm_validator->api_key->required, ); +sub user_create { + my ( $self, $params, undef, $remote_ip ) = @_; + + my $result = 0; + + eval { + my $allow = 0; + if ( defined $remote_ip ) { + $allow = 1 if ( $remote_ip eq '::1' || $remote_ip eq '127.0.0.1' || $remote_ip eq '::ffff:127.0.0.1' ); + } + else { + $allow = 1; + } + + if ( $allow ) { + $result = 1 if ( $self->{db}->add_api_user( $params->{username}, $params->{api_key} ) eq '1' ); + } + else { + die Zonemaster::Backend::Error::PermissionDenied->new( + message => 'Call to "add_api_user" method not permitted from a remote IP', + data => { remote_ip => $remote_ip } + ); + } + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{add_api_user} = $json_schemas{user_create}; sub add_api_user { my ( $self, $params, undef, $remote_ip ) = @_; @@ -487,7 +811,7 @@ sub add_api_user { return $result; } -$json_schemas{add_batch_job} = { +$json_schemas{batch_create} = { type => 'object', additionalProperties => 0, required => [ 'username', 'api_key', 'domains' ], @@ -524,6 +848,30 @@ $json_schemas{add_batch_job} = { } } }; +sub batch_create { + my ( $self, $params ) = @_; + + my $results; + eval { + $params->{test_params}{profile} //= "default"; + $params->{test_params}{priority} //= 5; + $params->{test_params}{queue} //= 0; + + my $profile = $self->{_profiles}{ $params->{test_params}{profile} }; + $params->{test_params}{ipv4} //= $profile->get( "net.ipv4" ); + $params->{test_params}{ipv6} //= $profile->get( "net.ipv6" ); + + $results = $self->{db}->add_batch_job( $params ); + }; + if ($@) { + handle_exception( $@ ); + } + + return $results; +} + +# Deprecated +$json_schemas{add_batch_job} = $json_schemas{batch_create}; sub add_batch_job { my ( $self, $params ) = @_; @@ -546,9 +894,27 @@ sub add_batch_job { return $results; } -$json_schemas{get_batch_job_result} = joi->object->strict->props( +$json_schemas{batch_status} = joi->object->strict->props( batch_id => $zm_validator->batch_id->required ); +sub batch_status { + my ( $self, $params ) = @_; + + my $result; + eval { + my $batch_id = $params->{batch_id}; + + $result = $self->{db}->get_batch_job_result($batch_id); + }; + if ($@) { + handle_exception( $@ ); + } + + return $result; +} + +# Deprecated +$json_schemas{get_batch_job_result} = $json_schemas{batch_status}; sub get_batch_job_result { my ( $self, $params ) = @_; From c619bec7ead1b828836c4d663ea36bdd4c18ca35 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 15:29:39 +0200 Subject: [PATCH 04/12] Refactor: reuse old API methods Some old API methods were already returning an object. This object can be returned. --- lib/Zonemaster/Backend/RPCAPI.pm | 162 +------------------------------ 1 file changed, 5 insertions(+), 157 deletions(-) diff --git a/lib/Zonemaster/Backend/RPCAPI.pm b/lib/Zonemaster/Backend/RPCAPI.pm index 756576076..a75daae17 100644 --- a/lib/Zonemaster/Backend/RPCAPI.pm +++ b/lib/Zonemaster/Backend/RPCAPI.pm @@ -121,19 +121,7 @@ sub system_versions { # Deprecated $json_schemas{version_info} = $json_schemas{system_versions}; sub version_info { - my ( $self ) = @_; - - my %ver; - eval { - $ver{zonemaster_ldns} = Zonemaster::LDNS->VERSION; - $ver{zonemaster_engine} = Zonemaster::Engine->VERSION; - $ver{zonemaster_backend} = Zonemaster::Backend->VERSION; - }; - if ($@) { - handle_exception( $@ ); - } - - return \%ver; + return system_versions( @_ ); } $json_schemas{conf_profiles} = joi->object->strict; @@ -308,41 +296,7 @@ sub lookup_delegation_data { # Deprecated $json_schemas{get_data_from_parent_zone} = $json_schemas{lookup_delegation_data}; sub get_data_from_parent_zone { - my ( $self, $params ) = @_; - - my $result = eval { - my %result; - my $domain = $params->{domain}; - - my @ns_list; - my @ns_names; - - my $zone = Zonemaster::Engine->zone( $domain ); - push @ns_list, { ns => $_->name->string, ip => $_->address->short} for @{$zone->glue}; - - my @ds_list; - - $zone = Zonemaster::Engine->zone($domain); - my $ds_p = $zone->parent->query_one( $zone->name, 'DS', { dnssec => 1, cd => 1, recurse => 1 } ); - if ($ds_p) { - my @ds = $ds_p->get_records( 'DS', 'answer' ); - - foreach my $ds ( @ds ) { - next unless $ds->type eq 'DS'; - push(@ds_list, { keytag => $ds->keytag, algorithm => $ds->algorithm, digtype => $ds->digtype, digest => $ds->hexdigest }); - } - } - - $result{ns_list} = \@ns_list; - $result{ds_list} = \@ds_list; - return \%result; - }; - if ($@) { - handle_exception( $@ ); - } - elsif ($result) { - return $result; - } + return lookup_delegation_data( @_ ); } $json_schemas{job_create} = { @@ -481,19 +435,7 @@ sub job_params { # Deprecated $json_schemas{get_test_params} = $json_schemas{job_params}; sub get_test_params { - my ( $self, $params ) = @_; - - my $result; - eval { - my $test_id = $params->{test_id}; - - $result = $self->{db}->get_test_params( $test_id ); - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + return job_params( @_ ); } $json_schemas{job_results} = { @@ -594,89 +536,7 @@ sub job_results { # Deprecated $json_schemas{get_test_results} = $json_schemas{job_results}; sub get_test_results { - my ( $self, $params ) = @_; - - my $result; - eval{ - - my $locale = $self->_get_locale( $params ); - - my $translator; - $translator = Zonemaster::Backend::Translator->new; - - my $previous_locale = $translator->locale; - if ( !$translator->locale( $locale ) ) { - die "Failed to set locale: $locale"; - } - - eval { $translator->data } if $translator; # Provoke lazy loading of translation data - - my @zm_results; - my %testcases; - - my $test_info = $self->{db}->test_results( $params->{id} ); - foreach my $test_res ( @{ $test_info->{results} } ) { - my $res; - if ( $test_res->{module} eq 'NAMESERVER' ) { - $res->{ns} = ( $test_res->{args}->{ns} ) ? ( $test_res->{args}->{ns} ) : ( 'All' ); - } - elsif ($test_res->{module} eq 'SYSTEM' - && $test_res->{tag} eq 'POLICY_DISABLED' - && $test_res->{args}->{name} eq 'Example' ) - { - next; - } - - $res->{module} = $test_res->{module}; - $res->{message} = $translator->translate_tag( $test_res ) . "\n"; - $res->{message} =~ s/,/, /isg; - $res->{message} =~ s/;/; /isg; - $res->{level} = $test_res->{level}; - $res->{testcase} = $test_res->{testcase} // 'UNSPECIFIED'; - $testcases{$res->{testcase}} = $translator->test_case_description($res->{testcase}); - - if ( $test_res->{module} eq 'SYSTEM' ) { - if ( $res->{message} =~ /policy\.json/ ) { - my ( $policy ) = ( $res->{message} =~ /\s(\/.*)$/ ); - if ( $policy ) { - my $policy_description = 'DEFAULT POLICY'; - $policy_description = 'SOME OTHER POLICY' if ( $policy =~ /some\/other\/policy\/path/ ); - $res->{message} =~ s/$policy/$policy_description/; - } - else { - $res->{message} = 'UNKNOWN POLICY FORMAT'; - } - } - elsif ( $res->{message} =~ /config\.json/ ) { - my ( $config ) = ( $res->{message} =~ /\s(\/.*)$/ ); - if ( $config ) { - my $config_description = 'DEFAULT CONFIGURATION'; - $config_description = 'SOME OTHER CONFIGURATION' if ( $config =~ /some\/other\/configuration\/path/ ); - $res->{message} =~ s/$config/$config_description/; - } - else { - $res->{message} = 'UNKNOWN CONFIG FORMAT'; - } - } - } - - push( @zm_results, $res ); - } - - $result = $test_info; - $result->{testcase_descriptions} = \%testcases; - $result->{results} = \@zm_results; - - $translator->locale( $previous_locale ); - - $result = $test_info; - $result->{results} = \@zm_results; - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + return job_results( @_ ); } $json_schemas{domain_history} = { @@ -916,19 +776,7 @@ sub batch_status { # Deprecated $json_schemas{get_batch_job_result} = $json_schemas{batch_status}; sub get_batch_job_result { - my ( $self, $params ) = @_; - - my $result; - eval { - my $batch_id = $params->{batch_id}; - - $result = $self->{db}->get_batch_job_result($batch_id); - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + return batch_status( @_ ); } sub _get_locale { From aea64a82dcee9ac25f0dd78428d111243aa77ee1 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 16:01:59 +0200 Subject: [PATCH 05/12] Always return an object in new API methods --- lib/Zonemaster/Backend/RPCAPI.pm | 71 ++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 21 deletions(-) diff --git a/lib/Zonemaster/Backend/RPCAPI.pm b/lib/Zonemaster/Backend/RPCAPI.pm index a75daae17..d72fd22bb 100644 --- a/lib/Zonemaster/Backend/RPCAPI.pm +++ b/lib/Zonemaster/Backend/RPCAPI.pm @@ -134,7 +134,10 @@ sub conf_profiles { handle_exception( $@ ); } - return [ keys %profiles ]; + my $result = { + profiles => [ keys %profiles ] + }; + return $result; } # Deprecated @@ -173,7 +176,11 @@ sub conf_languages { handle_exception( $@ ); } - return \@lang_tags; + my $result = { + languages => \@lang_tags + }; + + return $result; } # Deprecated @@ -210,20 +217,24 @@ $json_schemas{lookup_address_records} = { }; sub lookup_address_records { my ( $self, $params ) = @_; - my @adresses; + my @addresses; eval { my $ns_name = $params->{hostname}; - @adresses = map { {$ns_name => $_->short} } $recursor->get_addresses_for($ns_name); - @adresses = { $ns_name => '0.0.0.0' } if not @adresses; + @addresses = map { {$ns_name => $_->short} } $recursor->get_addresses_for($ns_name); + @addresses = { $ns_name => '0.0.0.0' } if not @addresses; }; if ($@) { handle_exception( $@ ); } - return \@adresses; + my $result = { + address_records => \@addresses + }; + + return $result; } # Deprecated @@ -327,7 +338,7 @@ $json_schemas{job_create} = { sub job_create { my ( $self, $params ) = @_; - my $result = 0; + my $job_id = 0; eval { $params->{domain} =~ s/^\.// unless ( !$params->{domain} || $params->{domain} eq '.' ); @@ -341,12 +352,16 @@ sub job_create { $params->{ipv4} //= $profile->get( "net.ipv4" ); $params->{ipv6} //= $profile->get( "net.ipv6" ); - $result = $self->{db}->create_new_test( $params->{domain}, $params, $self->{config}->ZONEMASTER_age_reuse_previous_test ); + $job_id = $self->{db}->create_new_test( $params->{domain}, $params, $self->{config}->ZONEMASTER_age_reuse_previous_test ); }; if ($@) { handle_exception( $@ ); } + my $result = { + job_id => $job_id + }; + return $result; } @@ -384,15 +399,19 @@ $json_schemas{job_status} = joi->object->strict->props( sub job_status { my ( $self, $params ) = @_; - my $result = 0; + my $progress = 0; eval { my $test_id = $params->{test_id}; - $result = $self->{db}->test_progress( $test_id ); + $progress = $self->{db}->test_progress( $test_id ); }; if ($@) { handle_exception( $@ ); } + my $result = { + progress => $progress + }; + return $result; } @@ -560,23 +579,25 @@ $json_schemas{domain_history} = { sub domain_history { my ( $self, $params ) = @_; - my $results; + my @history; eval { $params->{offset} //= 0; $params->{limit} //= 200; $params->{filter} //= "all"; - $results = $self->{db}->get_test_history( $params ); - my @results = map { { %$_, undelegated => $_->{undelegated} ? JSON::PP::true : JSON::PP::false } } @$results; - $results = \@results; - + my $results = $self->{db}->get_test_history( $params ); + @history = map { { %$_, undelegated => $_->{undelegated} ? JSON::PP::true : JSON::PP::false } } @$results; }; if ($@) { handle_exception( $@ ); } - return $results; + my $result = { + history => \@history + }; + + return $result; } # Deprecated @@ -610,7 +631,7 @@ $json_schemas{user_create} = joi->object->strict->props( sub user_create { my ( $self, $params, undef, $remote_ip ) = @_; - my $result = 0; + my $success = 0; eval { my $allow = 0; @@ -622,7 +643,7 @@ sub user_create { } if ( $allow ) { - $result = 1 if ( $self->{db}->add_api_user( $params->{username}, $params->{api_key} ) eq '1' ); + $success = 1 if ( $self->{db}->add_api_user( $params->{username}, $params->{api_key} ) eq '1' ); } else { die Zonemaster::Backend::Error::PermissionDenied->new( @@ -635,6 +656,10 @@ sub user_create { handle_exception( $@ ); } + my $result = { + success => $success + }; + return $result; } @@ -711,7 +736,7 @@ $json_schemas{batch_create} = { sub batch_create { my ( $self, $params ) = @_; - my $results; + my $batch_id; eval { $params->{test_params}{profile} //= "default"; $params->{test_params}{priority} //= 5; @@ -721,13 +746,17 @@ sub batch_create { $params->{test_params}{ipv4} //= $profile->get( "net.ipv4" ); $params->{test_params}{ipv6} //= $profile->get( "net.ipv6" ); - $results = $self->{db}->add_batch_job( $params ); + $batch_id = $self->{db}->add_batch_job( $params ); }; if ($@) { handle_exception( $@ ); } - return $results; + my $result = { + batch_id => $batch_id + }; + + return $result; } # Deprecated From 4dd6d09e218504c11dbe7f820c80adba6036d974 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 16:08:31 +0200 Subject: [PATCH 06/12] Reuse new API methods for deprecate one --- lib/Zonemaster/Backend/RPCAPI.pm | 160 ++++--------------------------- 1 file changed, 16 insertions(+), 144 deletions(-) diff --git a/lib/Zonemaster/Backend/RPCAPI.pm b/lib/Zonemaster/Backend/RPCAPI.pm index d72fd22bb..87f6abf69 100644 --- a/lib/Zonemaster/Backend/RPCAPI.pm +++ b/lib/Zonemaster/Backend/RPCAPI.pm @@ -143,15 +143,8 @@ sub conf_profiles { # Deprecated $json_schemas{profile_names} = $json_schemas{conf_profiles}; sub profile_names { - my ( $self ) = @_; - - my %profiles; - eval { %profiles = $self->{config}->PUBLIC_PROFILES }; - if ( $@ ) { - handle_exception( $@ ); - } - - return [ keys %profiles ]; + my $result = conf_profiles( @_ ); + return $result->{profiles}; } # Return the list of language tags supported by get_test_results(). The tags are @@ -186,25 +179,8 @@ sub conf_languages { # Deprecated $json_schemas{get_language_tags} = $json_schemas{conf_languages}; sub get_language_tags { - my ( $self ) = @_; - - my @lang_tags; - eval { - my %locales = $self->{config}->LANGUAGE_locale; - - for my $lang ( sort keys %locales ) { - my @locale_tags = sort keys %{ $locales{$lang} }; - if ( scalar @locale_tags == 1 ) { - push @lang_tags, $lang; - } - push @lang_tags, @locale_tags; - } - }; - if ( $@ ) { - handle_exception( $@ ); - } - - return \@lang_tags; + my $result = conf_languages( @_ ); + return $result->{languages}; } $json_schemas{lookup_address_records} = { @@ -240,21 +216,8 @@ sub lookup_address_records { # Deprecated $json_schemas{get_host_by_name} = $json_schemas{lookup_address_records}; sub get_host_by_name { - my ( $self, $params ) = @_; - my @adresses; - - eval { - my $ns_name = $params->{hostname}; - - @adresses = map { {$ns_name => $_->short} } $recursor->get_addresses_for($ns_name); - @adresses = { $ns_name => '0.0.0.0' } if not @adresses; - - }; - if ($@) { - handle_exception( $@ ); - } - - return \@adresses; + my $result = lookup_address_records( @_ ); + return $result->{address_records}; } $json_schemas{lookup_delegation_data} = { @@ -368,29 +331,8 @@ sub job_create { # Deprecated $json_schemas{start_domain_test} = $json_schemas{job_create}; sub start_domain_test { - my ( $self, $params ) = @_; - - my $result = 0; - eval { - $params->{domain} =~ s/^\.// unless ( !$params->{domain} || $params->{domain} eq '.' ); - - die "No domain in parameters\n" unless ( defined $params->{domain} && length($params->{domain}) ); - - $params->{profile} //= "default"; - $params->{priority} //= 10; - $params->{queue} //= 0; - - my $profile = $self->{_profiles}{ $params->{profile} }; - $params->{ipv4} //= $profile->get( "net.ipv4" ); - $params->{ipv6} //= $profile->get( "net.ipv6" ); - - $result = $self->{db}->create_new_test( $params->{domain}, $params, $self->{config}->ZONEMASTER_age_reuse_previous_test ); - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + my $result = job_create( @_ ); + return $result->{job_id}; } $json_schemas{job_status} = joi->object->strict->props( @@ -418,18 +360,8 @@ sub job_status { # Deprecated $json_schemas{test_progress} = $json_schemas{job_create}; sub test_progress { - my ( $self, $params ) = @_; - - my $result = 0; - eval { - my $test_id = $params->{test_id}; - $result = $self->{db}->test_progress( $test_id ); - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + my $result = job_status( @_ ); + return $result->{progress}; } $json_schemas{job_params} = joi->object->strict->props( @@ -603,25 +535,8 @@ sub domain_history { # Deprecated $json_schemas{get_test_history} = $json_schemas{domain_history}; sub get_test_history { - my ( $self, $params ) = @_; - - my $results; - - eval { - $params->{offset} //= 0; - $params->{limit} //= 200; - $params->{filter} //= "all"; - - $results = $self->{db}->get_test_history( $params ); - my @results = map { { %$_, undelegated => $_->{undelegated} ? JSON::PP::true : JSON::PP::false } } @$results; - $results = \@results; - - }; - if ($@) { - handle_exception( $@ ); - } - - return $results; + my $result = domain_history( @_ ); + return $result->{history}; } $json_schemas{user_create} = joi->object->strict->props( @@ -666,34 +581,8 @@ sub user_create { # Deprecated $json_schemas{add_api_user} = $json_schemas{user_create}; sub add_api_user { - my ( $self, $params, undef, $remote_ip ) = @_; - - my $result = 0; - - eval { - my $allow = 0; - if ( defined $remote_ip ) { - $allow = 1 if ( $remote_ip eq '::1' || $remote_ip eq '127.0.0.1' || $remote_ip eq '::ffff:127.0.0.1' ); - } - else { - $allow = 1; - } - - if ( $allow ) { - $result = 1 if ( $self->{db}->add_api_user( $params->{username}, $params->{api_key} ) eq '1' ); - } - else { - die Zonemaster::Backend::Error::PermissionDenied->new( - message => 'Call to "add_api_user" method not permitted from a remote IP', - data => { remote_ip => $remote_ip } - ); - } - }; - if ($@) { - handle_exception( $@ ); - } - - return $result; + my $result = user_create( @_ ); + return $result->{success}; } $json_schemas{batch_create} = { @@ -762,25 +651,8 @@ sub batch_create { # Deprecated $json_schemas{add_batch_job} = $json_schemas{batch_create}; sub add_batch_job { - my ( $self, $params ) = @_; - - my $results; - eval { - $params->{test_params}{profile} //= "default"; - $params->{test_params}{priority} //= 5; - $params->{test_params}{queue} //= 0; - - my $profile = $self->{_profiles}{ $params->{test_params}{profile} }; - $params->{test_params}{ipv4} //= $profile->get( "net.ipv4" ); - $params->{test_params}{ipv6} //= $profile->get( "net.ipv6" ); - - $results = $self->{db}->add_batch_job( $params ); - }; - if ($@) { - handle_exception( $@ ); - } - - return $results; + my $result = batch_create( @_ ); + return $result->{batch_id}; } $json_schemas{batch_status} = joi->object->strict->props( From af0f09857555e078540c01d87f2d87a01d8266de Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 16:59:44 +0200 Subject: [PATCH 07/12] Adapt documentation * Document new API methods * Mark old API methods as deprecated * Link to new API methods from deprecated one * Update return values for new API methods --- docs/API.md | 508 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 331 insertions(+), 177 deletions(-) diff --git a/docs/API.md b/docs/API.md index 8029b2fa8..0f39c1376 100644 --- a/docs/API.md +++ b/docs/API.md @@ -30,20 +30,35 @@ * [Timestamp (deprecated)](#timestamp-deprecated) * [Timestamp](#timestamp) * [Username](#username) -* [API method: version_info](#api-method-version_info) -* [API method: profile_names](#api-method-profile_names) -* [API method: get_language_tags](#api-method-get_language_tags) -* [API method: get_host_by_name](#api-method-get_host_by_name) -* [API method: get_data_from_parent_zone](#api-method-get_data_from_parent_zone) -* [API method: start_domain_test](#api-method-start_domain_test) -* [API method: test_progress](#api-method-test_progress) -* [API method: get_test_results](#api-method-get_test_results) -* [API method: get_test_history](#api-method-get_test_history) - * [Undelegated and delegated](#undelegated-and-delegated) -* [API method: add_api_user](#api-method-add_api_user) -* [API method: add_batch_job](#api-method-add_batch_job) -* [API method: get_batch_job_result](#api-method-get_batch_job_result) -* [API method: get_test_params](#api-method-get_test_params) +* [API methods](#api-methods) + * [API method: system_versions](#api-method-system_versions) + * [API method: conf_profiles](#api-method-conf_profiles) + * [API method: conf_languages](#api-method-conf_languages) + * [API method: lookup_address_records](#api-method-lookup_address_records) + * [API method: lookup_delegation_data](#api-method-lookup_delegation_data) + * [API method: job_create](#api-method-job_create) + * [API method: job_status](#api-method-job_status) + * [API method: job_results](#api-method-job_results) + * [API method: job_params](#api-method-job_params) + * [API method: domain_history](#api-method-domain_history) + * [Undelegated and delegated](#undelegated-and-delegated) + * [API method: user_create](#api-method-user_create) + * [API method: batch_create](#api-method-batch_create) + * [API method: batch_status](#api-method-batch_status) +* [Deprecated](#deprecated) + * [API method: version_info](#api-method-version_info) + * [API method: profile_names](#api-method-profile_names) + * [API method: get_language_tags](#api-method-get_language_tags) + * [API method: get_host_by_name](#api-method-get_host_by_name) + * [API method: get_data_from_parent_zone](#api-method-get_data_from_parent_zone) + * [API method: start_domain_test](#api-method-start_domain_test) + * [API method: test_progress](#api-method-test_progress) + * [API method: get_test_results](#api-method-get_test_results) + * [API method: get_test_history](#api-method-get_test_history) + * [API method: add_api_user](#api-method-add_api_user) + * [API method: add_batch_job](#api-method-add_batch_job) + * [API method: get_batch_job_result](#api-method-get_batch_job_result) + * [API method: get_test_params](#api-method-get_test_params) ## Purpose @@ -425,7 +440,9 @@ The items of the array are objects with two keys, `"path"` and `"message"`: referenced by `"path"`. -## API method: `version_info` +## API methods + +### API method: `system_versions` Returns the version of the Zonemaster-LDNS, Zonemaster-Engine and Zonemaster-Backend software combination. @@ -434,7 +451,7 @@ Example request: { "jsonrpc": "2.0", "id": 1, - "method": "version_info" + "method": "system_versions" } ``` @@ -452,7 +469,7 @@ Example response: ``` -#### `"result"` +##### `"result"` An object with the following properties: @@ -460,14 +477,14 @@ An object with the following properties: * `"zonemaster_engine"`: A string. The version number of the *Zonemaster Engine* used by the *RPC API daemon*. -#### `"error"` +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. > -## API method: `profile_names` +### API method: `conf_profiles` Returns the names of the public subset of the [available profiles][Profile sections]. @@ -477,7 +494,7 @@ Example request: { "jsonrpc": "2.0", "id": 1, - "method": "profile_names" + "method": "conf_profiles" } ``` @@ -486,20 +503,25 @@ Example response: { "jsonrpc": "2.0", "id": 1, - "result": [ - "default", - "another-profile" - ] + "result": { + "profiles": [ + "default", + "another-profile" + ] + } } ``` -#### `"result"` +##### `"result"` + +An oject with the following property: -An array of [*Profile names*][Profile name] in lower case. `"default"` is always included. +* `"profiles"`: An array of [*Profile names*][Profile name] in lower case. + `"default"` is always included. -## API method: `get_language_tags` +### API method: `conf_languages` Returns the set of valid [*language tags*][Language tag]. @@ -515,7 +537,7 @@ Example request: { "jsonrpc": "2.0", "id": 1, - "method": "get_language_tags" + "method": "conf_languages" } ``` @@ -524,32 +546,36 @@ Example response: { "jsonrpc": "2.0", "id": 1, - "result": [ - "da", - "da_DK", - "en", - "en_US", - "es", - "es_ES", - "fi", - "fi_FI", - "fr", - "fr_FR", - "nb", - "nb_NO", - "sv", - "sv_SE" - ] + "result": { + "languages": [ + "da", + "da_DK", + "en", + "en_US", + "es", + "es_ES", + "fi", + "fi_FI", + "fr", + "fr_FR", + "nb", + "nb_NO", + "sv", + "sv_SE" + ] + } } ``` -#### `"result"` +##### `"result"` + +An oject with the following property: -An array of [*language tags*][Language tag]. It is never empty. +* `"languages"`: An array of [*language tags*][Language tag]. It is never empty. -#### `"error"` +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for @@ -559,7 +585,7 @@ An array of [*language tags*][Language tag]. It is never empty. > -## API method: `get_host_by_name` +### API method: `lookup_address_records` Looks up the A and AAAA records for a hostname ([*domain name*][Domain name]) on the public Internet. @@ -570,7 +596,7 @@ Example request: { "jsonrpc": "2.0", "id": 2, - "method": "get_host_by_name", + "method": "lookup_address_records", "params": {"hostname": "zonemaster.net"} } ``` @@ -580,38 +606,43 @@ Example response: { "jsonrpc": "2.0", "id": 2, - "result": [ - { - "zonemaster.net": "192.134.4.83" - }, - { - "zonemaster.net": "2001:67c:2218:3::1:83" - } - ] + "result": { + "address_records": [ + { + "zonemaster.net": "192.134.4.83" + }, + { + "zonemaster.net": "2001:67c:2218:3::1:83" + } + ] + } } ``` -#### `"params"` +##### `"params"` An object with the property: * `"hostname"`: A [*domain name*][Domain name], required. The hostname whose IP addresses are to be resolved. -#### `"result"` +##### `"result"` + +An oject with the following property: -A list of one or two objects representing IP addresses (if 2 one is for IPv4 the -other for IPv6). The objects each have a single key and value. The key is the -[*domain name*][Domain name] given as input. The value is an IP address for the name, or the -value `0.0.0.0` if the lookup returned no A or AAAA records. +* `"address_record"`: A list of one or two objects representing IP addresses + (if 2 one is for IPv4 the other for IPv6). The objects each have a single key + and value. The key is the [*domain name*][Domain name] given as input. The + value is an IP address for the name, or the value `0.0.0.0` if the lookup + returned no A or AAAA records. > > TODO: If the name resolves to two or more IPv4 address, how is that represented? > -#### `"error"` +##### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -634,7 +665,7 @@ value `0.0.0.0` if the lookup returned no A or AAAA records. } ``` -## API method: `get_data_from_parent_zone` +### API method: `lookup_delegation_data` Returns all the NS/IP and DS/DNSKEY/ALGORITHM pairs of the domain from the parent zone. @@ -645,7 +676,7 @@ Example request: { "jsonrpc": "2.0", "id": 3, - "method": "get_data_from_parent_zone", + "method": "lookup_delegation_data", "params": {"domain": "zonemaster.net"} } ``` @@ -692,7 +723,7 @@ Example response: > -#### `"params"` +##### `"params"` An object with the properties: @@ -700,7 +731,7 @@ An object with the properties: * `"language"`: A [*language tag*][Language tag], optional, used for validation error messages translation, if not provided messages will be untranslated (in English). -#### `"result"` +##### `"result"` An object with the following properties: @@ -708,7 +739,7 @@ An object with the following properties: * `"ds_list"`: A list of [*DS info*][DS info] objects representing delegation signer (DS record data) of the given [*domain name*][Domain name]. -#### `"error"` +##### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -732,7 +763,7 @@ An object with the following properties: ``` -## API method: `start_domain_test` +### API method: `job_create` Enqueues a new *test* and returns the [*test id*][Test id] of the *test*. @@ -741,7 +772,7 @@ Example request: { "jsonrpc": "2.0", "id": 4, - "method": "start_domain_test", + "method": "job_create", "params": { "client_id": "Zonemaster Dancer Frontend", "domain": "zonemaster.net", @@ -769,12 +800,14 @@ Example response: { "jsonrpc": "2.0", "id": 4, - "result": "c45a3f8256c4a155" + "result": { + "job_id": "c45a3f8256c4a155" + } } ``` -#### `"params"` +##### `"params"` An object with the following properties: @@ -793,9 +826,11 @@ An object with the following properties: translation, if not provided messages will be untranslated. -#### `"result"` +##### `"result"` + +An object with the following property: -A [*test id*][Test id]. +* `"job_id"`: A [*test id*][Test id]. If a test has been requested with the same parameters (as listed below) not more than "reuse time" ago, then a new request will not trigger a new test. Instead @@ -808,7 +843,7 @@ The parameters that are compared when to determine if two requests are to be considered to be the same are `domain`, `ipv6`, `ipv4`, `nameservers`, `ds_info` and `profile`. -#### `"error"` +##### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -853,7 +888,7 @@ Example of error response: -## API method: `test_progress` +### API method: `job_status` Reports on the progress of a *test*. @@ -864,7 +899,7 @@ Example request: { "jsonrpc": "2.0", "id": 5, - "method": "test_progress", + "method": "job_status", "params": {"test_id": "c45a3f8256c4a155"} } ``` @@ -874,31 +909,35 @@ Example response: { "jsonrpc": "2.0", "id": 5, - "result": 100 + "result": { + "progress": 100 + } } ``` -#### `"params"` +##### `"params"` An object with the property: `"test_id"`: A [*test id*][Test id], required. The *test* to report on. -#### `"result"` +##### `"result"` + +An object with the following property: -A [*progress percentage*][Progress percentage]. +* `"progress"`: A [*progress percentage*][Progress percentage]. -#### `"error"` +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. > -## API method: `get_test_results` +### API method: `job_results` Return all [*test result*][Test result] objects of a *test*, with *messages* in the requested language as selected by the [*language tag*][Language tag]. @@ -908,7 +947,7 @@ Example request: { "jsonrpc": "2.0", "id": 6, - "method": "get_test_results", + "method": "job_results", "params": { "id": "c45a3f8256c4a155", "language": "en" @@ -975,7 +1014,7 @@ Example response: > -#### `"params"` +##### `"params"` An object with the following properties: @@ -983,7 +1022,9 @@ An object with the following properties: * `"language"`: A [*language tag*][Language tag], required. -#### `"result"` +##### `"result"` + +An object with the following properties: * `"created_at"`: A [*timestamp*][Timestamp]. The time in UTC at which the *test* was created. @@ -1011,14 +1052,78 @@ is a normalized version of an object created from the following parts: > -#### `"error"` +##### `"error"` + +> +> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. +> + + +### API method: `job_params` + +Return a normalized *params* objects of a *test*. + +Example request: + +*Valid syntax:* +```json +{ + "jsonrpc": "2.0", + "id": 143014426992009, + "method": "job_params", + "params": {"test_id": "6814584dc820354a"} +} +``` + +Example response: +```json +{ + "jsonrpc": "2.0", + "id": 143014426992009, + "result": { + "domain": "zonemaster.net", + "profile": "default", + "client_id": "Zonemaster Dancer Frontend", + "nameservers": [ + { + "ns": "ns3.nic.se", + "ip": "2001:67c:124c:2007::45" + }, + { + "ip": "192.93.0.4", + "ns": "ns2.nic.fr" + } + ], + "ipv4": true, + "ipv6": true, + "client_version": "1.0.1", + "ds_info": [] + } +} +``` + + +##### `"params"` + +An object with the property: + +* `"test_id"`: A [*test id*][Test id], required. + + +##### `"result"` + +The `"params"` object sent to [`start_domain_test`][start_domain_test] or +[`add_batch_job`][add_batch_job] when the *test* was started. + + +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. > -## API method: `get_test_history` +### API method: `domain_history` Returns a list of completed *tests* for a domain. @@ -1027,7 +1132,7 @@ Example request: { "jsonrpc": "2.0", "id": 7, - "method": "get_test_history", + "method": "domain_history", "params": { "offset": 0, "limit": 200, @@ -1044,21 +1149,24 @@ Example response: { "id": 7, "jsonrpc": "2.0", - "result": [ - { - "id": "c45a3f8256c4a155", - "created_at": "2016-11-15T11:53:13Z", - "undelegated": true, - "overall_result": "error", - }, - { - "id": "32dd4bc0582b6bf9", - "undelegated": false, - "created_at": "2016-11-14T08:46:41Z", - "overall_result": "error", - }, - ... - ] + "result": { + "history": [ + { + "id": "c45a3f8256c4a155", + "created_at": "2016-11-15T11:53:13Z", + "undelegated": true, + "overall_result": "error", + }, + { + "id": "32dd4bc0582b6bf9", + "undelegated": false, + "creation_time": "2016-11-14 08:46:41.532047", + "created_at": "2016-11-14T08:46:41Z", + "overall_result": "error", + }, + ... + ] + } } ``` @@ -1068,14 +1176,14 @@ Example response: > symbol. > -### Undelegated and delegated +#### Undelegated and delegated A test is considered to be `"delegated"` below if the test was started, by [`start_domain_test`][start_domain_test] or [`add_batch_job`][add_batch_job] without specifying neither `"nameserver"` nor `"ds_info"`. Else it is considered to be `"undelegated"`. -#### `"params"` +##### `"params"` An object with the following properties: @@ -1089,7 +1197,7 @@ The value of "frontend_params" is an object with the following properties: * `"domain"`: A [*domain name*][Domain name], required. -#### `"result"` +##### `"result"` An object with the following properties: @@ -1108,14 +1216,14 @@ An object with the following properties: `"CRITICAL"`. * `"undelegated"`: `true` if the test is undelegated, `false` otherwise. -#### `"error"` +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. > -## API method: `add_api_user` +### API method: `user_create` In order to use the [`add_batch_job`][add_batch_job] method a [*username*][Username] and its [*api key*][Api key] must be added by this method. @@ -1129,7 +1237,7 @@ Example request: ```json { "jsonrpc": "2.0", - "method": "add_api_user", + "method": "user_create", "id": 4711, "params": { "username": "citron", @@ -1143,12 +1251,14 @@ Example response: { "id": 4711, "jsonrpc": "2.0", - "result": 1 + "result": { + "success": 1 + } } ``` -#### `"params"` +##### `"params"` An object with the following properties: @@ -1157,12 +1267,15 @@ An object with the following properties: added. -#### `"result"` +##### `"result"` -An integer. The value is equal to 1 if the registration is a success, or 0 if it failed. +An object with the following property: +* `"success"`: An integer. The value is equal to 1 if the registration is a + success, or 0 if it failed. -#### `"error"` + +##### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1243,7 +1356,7 @@ Trying to add a user when the method is disabled: } ``` -## API method: `add_batch_job` +### API method: `batch_create` Add a new *batch test* composed by a set of [*domain name*][Domain name] and a *params* object. All the domains will be tested using identical parameters. @@ -1263,7 +1376,7 @@ Example request: { "jsonrpc": "2.0", "id": 147559211348450, - "method": "add_batch_job", + "method": "batch_create", "params" : { "api_key": "fromage", "username": "citron", @@ -1282,12 +1395,14 @@ Example response: { "jsonrpc": "2.0", "id": 147559211348450, - "result": 8 + "result": { + "batch_id": 8 + } } ``` -#### `"params"` +##### `"params"` An object with the following properties: @@ -1310,12 +1425,14 @@ The value of `"test_params"` is an object with the following properties: * `"queue"`: A [*queue*][Queue], optional. (default: `0`) -#### `"result"` +##### `"result"` -A [*batch id*][Batch id]. +An object with the following property: +* `"batch_id"`: An integer. The [*batch id*][Batch id]. -#### `"error"` + +##### `"error"` * You cannot create a new batch job if a *batch* with unfinished *tests* already exists for this [*username*][Username]. @@ -1385,7 +1502,7 @@ Trying to add a batch when the method has been disabled. ``` -## API method: `get_batch_job_result` +### API method: `batch_status` Return all [*test id*][Test id] objects of a *batch test*, with the number of finshed *test*. @@ -1396,8 +1513,10 @@ Example request: { "jsonrpc": "2.0", "id": 147559211994909, - "method": "get_batch_job_result", - "params": {"batch_id": "8"} + "method": "batch_status", + "params": { + "batch_id": "8" + } } ``` @@ -1421,14 +1540,14 @@ Example response: ``` -#### `"params"` +##### `"params"` An object with the property: * `"batch_id"`: A [*batch id*][Batch id], required. -#### `"result"` +##### `"result"` An object with the following properties: @@ -1437,7 +1556,7 @@ An object with the following properties: * `"finished_test_ids"`: a list of [*test ids*][Test id]. The set of finished *tests* in this *batch*. -#### `"error"` +##### `"error"` If the `batch_id` is undefined the following error is returned: @@ -1455,86 +1574,119 @@ If the `batch_id` is undefined the following error is returned: } ``` -## API method: `get_test_params` -Return a normalized *params* objects of a *test*. +## Deprecated -Example request: +### API method: `version_info` -*Valid syntax:* -```json -{ - "jsonrpc": "2.0", - "id": 143014426992009, - "method": "get_test_params", - "params": {"test_id": "6814584dc820354a"} -} -``` +**Deprecated**. Same as [`system_versions`][system_versions]. -Example response: -```json -{ - "jsonrpc": "2.0", - "id": 143014426992009, - "result": { - "domain": "zonemaster.net", - "profile": "default", - "client_id": "Zonemaster Dancer Frontend", - "nameservers": [ - { - "ns": "ns3.nic.se", - "ip": "2001:67c:124c:2007::45" - }, - { - "ip": "192.93.0.4", - "ns": "ns2.nic.fr" - } - ], - "ipv4": true, - "ipv6": true, - "client_version": "1.0.1", - "ds_info": [] - } -} -``` +### API method: `profile_names` -#### `"params"` +**Deprecated**. +Same as [`conf_profiles`][conf_profiles], but returns only the array of +[*Profile names*][Profile name]. -An object with the property: -* `"test_id"`: A [*test id*][Test id], required. +### API method: `get_language_tags` +**Deprecated**. +Same as [`conf_languages`][conf_languages], but returns only the array of +[*language tags*][Language tag]. -#### `"result"` -The `"params"` object sent to [`start_domain_test`][start_domain_test] or -[`add_batch_job`][add_batch_job] when the *test* was started. +### API method: `get_host_by_name` +**Deprecated**. +Same as [`lookup_address_records`][lookup_address_records], but returns only the +array of objects. -#### `"error"` -> -> TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. -> +### API method: `get_data_from_parent_zone` + +**Deprecated**. +Same as [`lookup_delegation_data`][lookup_delegation_data]. + + +### API method: `start_domain_test` + +**Deprecated**. +Same as [`job_create`][job_create], but returns only the [*test id*][Test id]. + + +### API method: `test_progress` + +**Deprecated**. +Same as [`job_status`][job_status], but returns only the [*progress +percentage*][Progress percentage]. + + +### API method: `get_test_results` + +**Deprecated**. +Same as [`job_results`][job_results]. + + +### API method: `get_test_history` + +**Deprecated**. +Same as [`domain_history`][domain_history], but returns only the list of test +object. + + +### API method: `add_api_user` + +**Deprecated**. +Same as [`user_create`][user_create], but returns only the success value. + + +### API method: `add_batch_job` + +**Deprecated**. +Same as [`batch_create`][batch_create], but returns only the [*batch id*][Batch id]. + + +### API method: `get_batch_job_result` + +**Deprecated**. +Same as [`batch_status`][batch_status]. + + +### API method: `get_test_params` + +**Deprecated**. +Same as [`job_params`][job_params]. + [add_api_user]: #api-method-add_api_user [add_batch_job]: #api-method-add_batch_job [API key]: #api-key [Batch id]: #batch-id +[batch_create]: #api-method-batch_create +[batch_status]: #api-method-batch_status [Client id]: #client-id [Client version]: #client-version +[conf_languages]: #api-method-conf_languages +[conf_profiles]: #api-method-conf_profiles [Delegation Signer]: https://datatracker.ietf.org/doc/html/rfc4034#section-5 [Domain name]: #domain-name +[domain_history]: #api-method-domain_history [Dot-decimal notation]: https://en.wikipedia.org/wiki/Dot-decimal_notation [DS info]: #ds-info [IP address]: #ip-address [ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 [ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1 +[job_create]: #api-method-job_create +[job_params]: #api-method-job_params +[job_results]: #api-method-job_results +[job_status]: #api-method-job_status [JSON Pointer]: https://datatracker.ietf.org/doc/html/rfc6901 [JSON-RPC 2.0]: https://www.jsonrpc.org/specification [Language tag]: #language-tag [LANGUAGE.locale]: Configuration.md#locale +[lookup_address_records]: #api-method-lookup_address_records +[lookup_delegation_data]: #api-method-lookup_delegation_data [Name server]: #name-server [net.ipv4]: https://metacpan.org/pod/Zonemaster::Engine::Profile#net.ipv4 [net.ipv6]: https://metacpan.org/pod/Zonemaster::Engine::Profile#net.ipv6 @@ -1551,11 +1703,13 @@ The `"params"` object sent to [`start_domain_test`][start_domain_test] or [Severity Level Definitions]: https://github.com/zonemaster/zonemaster/blob/master/docs/specifications/tests/SeverityLevelDefinitions.md [Severity level]: #severity-level [start_domain_test]: #api-method-start_domain_test +[system_versions]: #api-method-system_versions [Test Cases]: https://github.com/zonemaster/zonemaster/tree/master/docs/specifications/tests#list-of-defined-test-cases [Test Case Identifiers]: https://github.com/zonemaster/zonemaster/blob/master/docs/internal-documentation/templates/specifications/tests/TestCaseIdentifierSpecification.md [Test id]: #test-id [Test result]: #test-result [Timestamp]: #timestamp +[user_create]: #api-method-user_create [Username]: #username [Validation error data]: #validation-error-data [ZONEMASTER.age_reuse_previous_test]: Configuration.md#age_reuse_previous_test From 3ccae1165f45959ecdf566371875893c96814411 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 12 Oct 2022 17:02:05 +0200 Subject: [PATCH 08/12] Document missing output --- docs/API.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/API.md b/docs/API.md index 0f39c1376..b9c0a5841 100644 --- a/docs/API.md +++ b/docs/API.md @@ -473,6 +473,7 @@ Example response: An object with the following properties: +* `"zonemaster_ldns"`: A string. The version number of the running *Zonemaster LDNS*. * `"zonemaster_backend"`: A string. The version number of the running *Zonemaster Backend*. * `"zonemaster_engine"`: A string. The version number of the *Zonemaster Engine* used by the *RPC API daemon*. From 51de6253cc358cf26846002c3350139b3e8da521 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Thu, 13 Oct 2022 14:00:55 +0200 Subject: [PATCH 09/12] Document deprecation removal time --- docs/API.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/API.md b/docs/API.md index b9c0a5841..9e5ee438d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1580,83 +1580,84 @@ If the `batch_id` is undefined the following error is returned: ### API method: `version_info` -**Deprecated**. Same as [`system_versions`][system_versions]. +**Deprecated** (planned removal: v2024.1). +Same as [`system_versions`][system_versions]. ### API method: `profile_names` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`conf_profiles`][conf_profiles], but returns only the array of [*Profile names*][Profile name]. ### API method: `get_language_tags` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`conf_languages`][conf_languages], but returns only the array of [*language tags*][Language tag]. ### API method: `get_host_by_name` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`lookup_address_records`][lookup_address_records], but returns only the array of objects. ### API method: `get_data_from_parent_zone` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`lookup_delegation_data`][lookup_delegation_data]. ### API method: `start_domain_test` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`job_create`][job_create], but returns only the [*test id*][Test id]. ### API method: `test_progress` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`job_status`][job_status], but returns only the [*progress percentage*][Progress percentage]. ### API method: `get_test_results` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`job_results`][job_results]. ### API method: `get_test_history` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`domain_history`][domain_history], but returns only the list of test object. ### API method: `add_api_user` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`user_create`][user_create], but returns only the success value. ### API method: `add_batch_job` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`batch_create`][batch_create], but returns only the [*batch id*][Batch id]. ### API method: `get_batch_job_result` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`batch_status`][batch_status]. ### API method: `get_test_params` -**Deprecated**. +**Deprecated** (planned removal: v2024.1). Same as [`job_params`][job_params]. From 53501b4127db35470e42e91b7de1148de7acfc77 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Thu, 13 Oct 2022 14:03:13 +0200 Subject: [PATCH 10/12] Reset some heading level --- docs/API.md | 72 ++++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/API.md b/docs/API.md index 9e5ee438d..e90285ddb 100644 --- a/docs/API.md +++ b/docs/API.md @@ -469,7 +469,7 @@ Example response: ``` -##### `"result"` +#### `"result"` An object with the following properties: @@ -478,7 +478,7 @@ An object with the following properties: * `"zonemaster_engine"`: A string. The version number of the *Zonemaster Engine* used by the *RPC API daemon*. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -514,7 +514,7 @@ Example response: ``` -##### `"result"` +#### `"result"` An oject with the following property: @@ -569,14 +569,14 @@ Example response: ``` -##### `"result"` +#### `"result"` An oject with the following property: * `"languages"`: An array of [*language tags*][Language tag]. It is never empty. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for @@ -621,14 +621,14 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the property: * `"hostname"`: A [*domain name*][Domain name], required. The hostname whose IP addresses are to be resolved. -##### `"result"` +#### `"result"` An oject with the following property: @@ -643,7 +643,7 @@ An oject with the following property: > -##### `"error"` +#### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -724,7 +724,7 @@ Example response: > -##### `"params"` +#### `"params"` An object with the properties: @@ -732,7 +732,7 @@ An object with the properties: * `"language"`: A [*language tag*][Language tag], optional, used for validation error messages translation, if not provided messages will be untranslated (in English). -##### `"result"` +#### `"result"` An object with the following properties: @@ -740,7 +740,7 @@ An object with the following properties: * `"ds_list"`: A list of [*DS info*][DS info] objects representing delegation signer (DS record data) of the given [*domain name*][Domain name]. -##### `"error"` +#### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -808,7 +808,7 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the following properties: @@ -827,7 +827,7 @@ An object with the following properties: translation, if not provided messages will be untranslated. -##### `"result"` +#### `"result"` An object with the following property: @@ -844,7 +844,7 @@ The parameters that are compared when to determine if two requests are to be considered to be the same are `domain`, `ipv6`, `ipv4`, `nameservers`, `ds_info` and `profile`. -##### `"error"` +#### `"error"` * If any parameter is invalid an error code of -32602 is returned. The `data` property contains an array of all errors, see [Validation error data]. @@ -917,21 +917,21 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the property: `"test_id"`: A [*test id*][Test id], required. The *test* to report on. -##### `"result"` +#### `"result"` An object with the following property: * `"progress"`: A [*progress percentage*][Progress percentage]. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1015,7 +1015,7 @@ Example response: > -##### `"params"` +#### `"params"` An object with the following properties: @@ -1023,7 +1023,7 @@ An object with the following properties: * `"language"`: A [*language tag*][Language tag], required. -##### `"result"` +#### `"result"` An object with the following properties: @@ -1053,7 +1053,7 @@ is a normalized version of an object created from the following parts: > -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1104,20 +1104,20 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the property: * `"test_id"`: A [*test id*][Test id], required. -##### `"result"` +#### `"result"` The `"params"` object sent to [`start_domain_test`][start_domain_test] or [`add_batch_job`][add_batch_job] when the *test* was started. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1177,14 +1177,14 @@ Example response: > symbol. > -#### Undelegated and delegated +### Undelegated and delegated A test is considered to be `"delegated"` below if the test was started, by [`start_domain_test`][start_domain_test] or [`add_batch_job`][add_batch_job] without specifying neither `"nameserver"` nor `"ds_info"`. Else it is considered to be `"undelegated"`. -##### `"params"` +#### `"params"` An object with the following properties: @@ -1198,7 +1198,7 @@ The value of "frontend_params" is an object with the following properties: * `"domain"`: A [*domain name*][Domain name], required. -##### `"result"` +#### `"result"` An object with the following properties: @@ -1217,7 +1217,7 @@ An object with the following properties: `"CRITICAL"`. * `"undelegated"`: `true` if the test is undelegated, `false` otherwise. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1259,7 +1259,7 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the following properties: @@ -1268,7 +1268,7 @@ An object with the following properties: added. -##### `"result"` +#### `"result"` An object with the following property: @@ -1276,7 +1276,7 @@ An object with the following property: success, or 0 if it failed. -##### `"error"` +#### `"error"` > > TODO: List all possible error codes and describe what they mean enough for clients to know how react to them. @@ -1403,7 +1403,7 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the following properties: @@ -1426,14 +1426,14 @@ The value of `"test_params"` is an object with the following properties: * `"queue"`: A [*queue*][Queue], optional. (default: `0`) -##### `"result"` +#### `"result"` An object with the following property: * `"batch_id"`: An integer. The [*batch id*][Batch id]. -##### `"error"` +#### `"error"` * You cannot create a new batch job if a *batch* with unfinished *tests* already exists for this [*username*][Username]. @@ -1541,14 +1541,14 @@ Example response: ``` -##### `"params"` +#### `"params"` An object with the property: * `"batch_id"`: A [*batch id*][Batch id], required. -##### `"result"` +#### `"result"` An object with the following properties: @@ -1557,7 +1557,7 @@ An object with the following properties: * `"finished_test_ids"`: a list of [*test ids*][Test id]. The set of finished *tests* in this *batch*. -##### `"error"` +#### `"error"` If the `batch_id` is undefined the following error is returned: From 720a6eb30d2b9f283a1641d8ab9fca0e1cfa2137 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Tue, 14 Feb 2023 10:57:45 +0100 Subject: [PATCH 11/12] Clarification for deprecated methods --- docs/API.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/API.md b/docs/API.md index e90285ddb..8c9b97dcb 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1578,6 +1578,9 @@ If the `batch_id` is undefined the following error is returned: ## Deprecated +> For details of the deprecated methods' return values see the [version of this +> document][API v10.0.0] included in the v2022.2 release, tagged as "v10.0.0". + ### API method: `version_info` **Deprecated** (planned removal: v2024.1). @@ -1587,22 +1590,18 @@ Same as [`system_versions`][system_versions]. ### API method: `profile_names` **Deprecated** (planned removal: v2024.1). -Same as [`conf_profiles`][conf_profiles], but returns only the array of -[*Profile names*][Profile name]. +Same as [`conf_profiles`][conf_profiles]. ### API method: `get_language_tags` **Deprecated** (planned removal: v2024.1). -Same as [`conf_languages`][conf_languages], but returns only the array of -[*language tags*][Language tag]. - +Same as [`conf_languages`][conf_languages]. ### API method: `get_host_by_name` **Deprecated** (planned removal: v2024.1). -Same as [`lookup_address_records`][lookup_address_records], but returns only the -array of objects. +Same as [`lookup_address_records`][lookup_address_records]. ### API method: `get_data_from_parent_zone` @@ -1614,39 +1613,36 @@ Same as [`lookup_delegation_data`][lookup_delegation_data]. ### API method: `start_domain_test` **Deprecated** (planned removal: v2024.1). -Same as [`job_create`][job_create], but returns only the [*test id*][Test id]. +Same as [`job_create`][job_create]. ### API method: `test_progress` **Deprecated** (planned removal: v2024.1). -Same as [`job_status`][job_status], but returns only the [*progress -percentage*][Progress percentage]. +Same as [`job_status`][job_status]. ### API method: `get_test_results` **Deprecated** (planned removal: v2024.1). -Same as [`job_results`][job_results]. ### API method: `get_test_history` **Deprecated** (planned removal: v2024.1). -Same as [`domain_history`][domain_history], but returns only the list of test -object. +Same as [`domain_history`][domain_history]. ### API method: `add_api_user` **Deprecated** (planned removal: v2024.1). -Same as [`user_create`][user_create], but returns only the success value. +Same as [`user_create`][user_create]. ### API method: `add_batch_job` **Deprecated** (planned removal: v2024.1). -Same as [`batch_create`][batch_create], but returns only the [*batch id*][Batch id]. +Same as [`batch_create`][batch_create]. ### API method: `get_batch_job_result` @@ -1663,6 +1659,7 @@ Same as [`job_params`][job_params]. [add_api_user]: #api-method-add_api_user [add_batch_job]: #api-method-add_batch_job +[API v10.0.0]: https://github.com/zonemaster/zonemaster-backend/blob/v10.0.0/docs/API.md [API key]: #api-key [Batch id]: #batch-id [batch_create]: #api-method-batch_create From 64d457faf209ba5390e76414657ef8fc75c51e42 Mon Sep 17 00:00:00 2001 From: Alexandre Pion Date: Wed, 22 Feb 2023 18:17:54 +0100 Subject: [PATCH 12/12] New configuration parameter in RPCAPI section * create "RPCAPI.enable_batch_create" and "RPCAPI.enable_user_create" * mark "RPCAPI.enable_add_batch_job" and "RPCAPI.enable_add_api_user" as deprecated --- docs/Configuration.md | 29 +++++++++++++++++++++++---- lib/Zonemaster/Backend/Config.pm | 28 ++++++++++++++++++++++---- script/zonemaster_backend_rpcapi.psgi | 4 ++-- 3 files changed, 51 insertions(+), 10 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index e2226bce6..bed34ad43 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -4,6 +4,8 @@ * [Introduction](#introduction) * [RPCAPI section](#rpcapi-section) + * [enable_batch_create](#enable_batch_create) + * [enable_user_create](#enable_user_create) * [enable_add_batch_job](#enable_add_batch_job) * [enable_add_api_user](#enable_add_api_user) * [DB section](#db-section) @@ -61,22 +63,39 @@ In addition to the configuration file, some settings can configured using ## RPCAPI section -Available keys: `enable_add_batch_job`, `enable_add_api_user`. +Available keys: `enable_batch_create`, `enable_user_create`, +`enable_add_batch_job`, `enable_add_api_user`. -### enable_add_batch_job +### enable_batch_create -Boolean value to enable the `enable_add_batch_job` methods of the API. +Boolean value to enable the `batch_create` methods of the API. Accepted values: `yes` (or `true`) or `no` (or `false`), default to `yes` (enabled). ### enable_add_api_user -Boolean value to enable the `add_api_user` method of the API. +Boolean value to enable the `user_create` method of the API. Accepted values: `yes` (or `true`) or `no` (or `false`), default to `no` (disabled). +### enable_add_batch_job + +Deprecated (planned removal: v2024.1). Use +[enable_batch_create][RPCAPI.enable_batch_create] instead. + +The [enable_batch_create][RPCAPI.enable_batch_create] property takes +precedence over this. + +### enable_add_api_user + +Deprecated (planned removal: v2024.1). Use +[enable_user_create][RPCAPI.enable_user_create] instead. + +The [enable_user_create][RPCAPI.enable_user_create] property takes +precedence over this. + ## DB section @@ -399,6 +418,8 @@ Otherwise a new test request is enqueued. [Profile JSON files]: https://github.com/zonemaster/zonemaster-engine/blob/master/docs/Profiles.md [Profile name section]: API.md#profile-name [Profiles]: Architecture.md#profile +[RPCAPI.enable_batch_create]: #enable_batch_create +[RPCAPI.enable_user_create]: #enable_user_create [SQLITE.database_file]: #database_file [US ASCII printable characters]: https://en.wikipedia.org/wiki/ASCII#Printable_characters [Zonemaster-Engine share directory]: https://github.com/zonemaster/zonemaster-engine/tree/master/share diff --git a/lib/Zonemaster/Backend/Config.pm b/lib/Zonemaster/Backend/Config.pm index fa0f0fcce..467fa1c24 100644 --- a/lib/Zonemaster/Backend/Config.pm +++ b/lib/Zonemaster/Backend/Config.pm @@ -215,6 +215,8 @@ sub parse { $obj->_set_ZONEMASTER_number_of_processes_for_batch_testing( '20' ); $obj->_set_ZONEMASTER_lock_on_queue( '0' ); $obj->_set_ZONEMASTER_age_reuse_previous_test( '600' ); + $obj->_set_RPCAPI_enable_user_create( 'no' ); + $obj->_set_RPCAPI_enable_batch_create( 'yes' ); $obj->_set_RPCAPI_enable_add_api_user( 'no' ); $obj->_set_RPCAPI_enable_add_batch_job( 'yes' ); $obj->_add_LANGUAGE_locale( 'en_US' ); @@ -589,7 +591,6 @@ L. + +Return 0 or 1 + + +=head2 RPCAPI_enable_batch_create + +Get the value of +L. + +Return 0 or 1 + =head2 RPCAPI_enable_add_api_user +Deprecated (planned removal: v2024.1). Get the value of L. Return 0 or 1 -=cut =head2 RPCAPI_enable_add_batch_job +Deprecated (planned removal: v2024.1). Get the value of L. @@ -650,6 +666,8 @@ sub ZONEMASTER_number_of_processes_for_batch_testing { return $_[0]->{_ZONEMA sub ZONEMASTER_age_reuse_previous_test { return $_[0]->{_ZONEMASTER_age_reuse_previous_test}; } sub METRICS_statsd_host { return $_[0]->{_METRICS_statsd_host}; } sub METRICS_statsd_port { return $_[0]->{_METRICS_statsd_port}; } +sub RPCAPI_enable_user_create { return $_[0]->{_RPCAPI_enable_user_create}; } +sub RPCAPI_enable_batch_create { return $_[0]->{_RPCAPI_enable_batch_create}; } sub RPCAPI_enable_add_api_user { return $_[0]->{_RPCAPI_enable_add_api_user}; } sub RPCAPI_enable_add_batch_job { return $_[0]->{_RPCAPI_enable_add_batch_job}; } @@ -674,6 +692,8 @@ UNITCHECK { _create_setter( '_set_ZONEMASTER_age_reuse_previous_test', '_ZONEMASTER_age_reuse_previous_test', \&untaint_strictly_positive_int ); _create_setter( '_set_METRICS_statsd_host', '_METRICS_statsd_host', \&untaint_host ); _create_setter( '_set_METRICS_statsd_port', '_METRICS_statsd_port', \&untaint_strictly_positive_int ); + _create_setter( '_set_RPCAPI_enable_user_create', '_RPCAPI_enable_user_create', \&untaint_bool ); + _create_setter( '_set_RPCAPI_enable_batch_create', '_RPCAPI_enable_batch_create', \&untaint_bool ); _create_setter( '_set_RPCAPI_enable_add_api_user', '_RPCAPI_enable_add_api_user', \&untaint_bool ); _create_setter( '_set_RPCAPI_enable_add_batch_job', '_RPCAPI_enable_add_batch_job', \&untaint_bool ); } diff --git a/script/zonemaster_backend_rpcapi.psgi b/script/zonemaster_backend_rpcapi.psgi index f219b51ea..91dae2cf1 100644 --- a/script/zonemaster_backend_rpcapi.psgi +++ b/script/zonemaster_backend_rpcapi.psgi @@ -181,7 +181,7 @@ my $router = router { }; }; -if ($config->RPCAPI_enable_add_api_user) { +if ( $config->RPCAPI_enable_user_create or $config->RPCAPI_enable_add_api_user ) { $log->info('Enabling user_create method'); #Deprecated $router->connect("add_api_user", { @@ -194,7 +194,7 @@ if ($config->RPCAPI_enable_add_api_user) { }); } -if ($config->RPCAPI_enable_add_batch_job) { +if ( $config->RPCAPI_enable_batch_create or $config->RPCAPI_enable_add_batch_job ) { $log->info('Enabling batch_create method'); #Deprecated $router->connect("add_batch_job", {