AdGuardDNS/internal/backendpb/dns.proto

syntax = "proto3";

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

option java_multiple_files = true;
option java_package = "com.adguard.backend.dns.generated";
option java_outer_classname = "DNSProfilesProto";
option objc_class_prefix = "DNS";

service DNSService {

  /*
    Gets DNS profiles.

    Field "sync_time" in DNSProfilesRequest - pass to return the latest updates after this time moment.

    The trailers headers will include a "sync_time", given in milliseconds,
    that should be used for subsequent incremental DNS profile synchronization requests.

    This method may return the following errors:
    - RateLimitedError: If too many "full sync" concurrent requests are made.
    - AuthenticationFailedError: If the authentication failed.
  */
  rpc getDNSProfiles(DNSProfilesRequest) returns (stream DNSProfile);

  /*
    Stores devices activity.

    This method may return the following errors:
    - AuthenticationFailedError: If the authentication failed.
  */
  rpc saveDevicesBillingStat(stream DeviceBillingStat) returns (google.protobuf.Empty);

  /*
    Create device by "human_id".

    This method may return the following errors:
    - RateLimitedError: If the request was made too frequently and the client must wait before retrying.
    - DeviceQuotaExceededError: If the client has exceeded its quota for creating devices.
    - BadRequestError: If the request is invalid: DNS server does not exist, creation of auto-devices is disabled or human_id validation failed.
    - AuthenticationFailedError: If the authentication failed.
  */
  rpc createDeviceByHumanId(CreateDeviceRequest) returns (CreateDeviceResponse);
}

service RateLimitService {

  /*
    Gets rate limit settings.
  */
  rpc getRateLimitSettings(RateLimitSettingsRequest) returns (RateLimitSettingsResponse);
}

service RemoteKVService {

  /**
    Get the value for the specified key.

    This method may return the following errors:
    - AuthenticationFailedError: If the authentication failed.
   */
  rpc get(RemoteKVGetRequest) returns (RemoteKVGetResponse);

  /**
    Set the value for the specified key.

    This method may return the following errors:
    - AuthenticationFailedError: If the authentication failed.
    - BadRequestError: If the request is invalid: value size exceeds the 512kb.
   */
  rpc set(RemoteKVSetRequest) returns (RemoteKVSetResponse);
}

message RateLimitSettingsRequest {

}

message RateLimitSettingsResponse {
  repeated CidrRange allowed_subnets = 1;
}

message DNSProfilesRequest {
  google.protobuf.Timestamp sync_time = 1;
}

message DNSProfile {
  string dns_id = 1;
  bool filtering_enabled = 2;
  bool query_log_enabled = 3;
  bool deleted = 4;
  SafeBrowsingSettings safe_browsing = 5;
  ParentalSettings parental = 6;
  RuleListsSettings rule_lists = 7;
  repeated DeviceSettings devices = 8;
  repeated string custom_rules = 9;
  google.protobuf.Duration filtered_response_ttl = 10;
  bool block_private_relay = 11;
  bool block_firefox_canary = 12;
  oneof blocking_mode {
    BlockingModeCustomIP blocking_mode_custom_ip = 13;
    BlockingModeNXDOMAIN blocking_mode_nxdomain = 14;
    BlockingModeNullIP blocking_mode_null_ip = 15;
    BlockingModeREFUSED blocking_mode_refused = 16;
  }
  bool ip_log_enabled = 17;
  AccessSettings access = 18;
  bool auto_devices_enabled = 19;
  RateLimitSettings rate_limit = 20;
  bool block_chrome_prefetch = 21;
}

message SafeBrowsingSettings {
  bool enabled = 1;
  bool block_dangerous_domains = 2;
  bool block_nrd = 3;
}

message DeviceSettings {
  string id = 1;
  string name = 2;
  bool filtering_enabled = 3;
  bytes linked_ip = 4;
  repeated bytes dedicated_ips = 5;
  AuthenticationSettings authentication = 6;
  // Value in lower case. Will be empty for "ordinary" devices and non-empty for "automatically" created devices.
  string human_id_lower = 7;
}

message ParentalSettings {
  bool enabled = 1;
  bool block_adult = 2;
  bool general_safe_search = 3;
  bool youtube_safe_search = 4;
  repeated string blocked_services = 5;
  ScheduleSettings schedule = 6;
}

message ScheduleSettings {
  string tmz = 1;
  WeeklyRange weeklyRange = 2;
}

message WeeklyRange {
  DayRange mon = 1;
  DayRange tue = 2;
  DayRange wed = 3;
  DayRange thu = 4;
  DayRange fri = 5;
  DayRange sat = 6;
  DayRange sun = 7;
}

message DayRange {
  google.protobuf.Duration start = 1;
  google.protobuf.Duration end = 2;
}

message RuleListsSettings {
  bool enabled = 1;
  repeated string ids = 2;
}

message BlockingModeCustomIP {
  bytes ipv4 = 1;
  bytes ipv6 = 2;
}

message BlockingModeNXDOMAIN {}

message BlockingModeNullIP {}

message BlockingModeREFUSED {}

message DeviceBillingStat {
  google.protobuf.Timestamp last_activity_time = 1;
  string device_id = 2;
  string client_country = 3;
  // Protocol type. Possible values see here: https://bit.adguard.com/projects/DNS/repos/dns-server/browse#ql-properties
  uint32 proto = 4;
  uint32 asn = 5;
  uint32 queries = 6;
}

message AccessSettings {
  repeated CidrRange allowlist_cidr = 1;
  repeated CidrRange blocklist_cidr = 2;
  repeated uint32 allowlist_asn = 3;
  repeated uint32 blocklist_asn = 4;
  repeated string blocklist_domain_rules = 5;
  bool enabled = 6;
}

message CidrRange {
  bytes address = 1;
  uint32 prefix = 2;
}

message AuthenticationSettings {
  bool doh_auth_only = 1;
  oneof doh_password_hash {
    bytes password_hash_bcrypt = 2;
  }
}

enum DeviceType {
  INVALID = 0;
  WINDOWS = 1;
  ANDROID = 2;
  MAC = 3;
  IOS = 4;
  LINUX = 5;
  ROUTER = 6;
  SMART_TV = 7;
  GAME_CONSOLE = 8;
  OTHER = 9;
}

message CreateDeviceRequest {
  string dns_id = 1;
  string human_id = 2;
  DeviceType device_type = 3;
}

message CreateDeviceResponse {
  DeviceSettings device = 1;
}

message RateLimitedError {
  string message = 1;
  google.protobuf.Duration retry_delay = 2;
}

message DeviceQuotaExceededError {
  string message = 1;
}

message BadRequestError {
  string message = 1;
}

message AuthenticationFailedError {
  string message = 1;
}

message RateLimitSettings {
  bool enabled = 1;
  uint32 rps = 2;
  repeated CidrRange client_cidr = 3;
}

message RemoteKVGetRequest {
  string key = 1;
}

message RemoteKVGetResponse {
  oneof value {
    bytes data = 1;
    google.protobuf.Empty empty = 2;
  }
}

message RemoteKVSetRequest {
  string key = 1;
  bytes data = 2;
  google.protobuf.Duration ttl = 3;
}

message RemoteKVSetResponse {

}