Feature: defines the contracts and add sentinel errors

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: latest
+
+      - name: Run tests
+        run: make unit-test

.gitignore

@@ -0,0 +1,27 @@
+# Binaries
+bin/
+build/
+
+# Test output and profiles
+*.test
+*.out
+cover.html
+
+# Environment variables
+.env
+.env.local
+
+# IDEs and OS specific
+.idea/
+.vscode/
+.DS_Store
+
+# Go workspaces
+go.work
+go.work.sum
+
+# Vendor directory
+vendor/
+
+# MD documentation
+TASK.md

.golangci.yaml

@@ -0,0 +1,86 @@
+version: "2"
+
+run:
+  timeout: 5m
+  tests: true
+  modules-download-mode: readonly
+
+formatters:
+  enable:
+    - gofumpt
+    - goimports
+  settings:
+    goimports:
+      local-prefixes:
+        - github.com/ilindan-dev/dns-manager
+
+linters:
+  default: none
+
+  enable:
+    - errcheck
+    - govet
+    - staticcheck
+    - unused
+    - ineffassign
+
+    - bodyclose
+    - sqlclosecheck
+    - rowserrcheck
+    - copyloopvar
+    - makezero
+    - prealloc
+
+    - gosec
+    - gocritic
+    - errorlint
+    - nilerr
+    - nilnil
+    - revive
+    - lll
+    - gocyclo
+    - gocognit
+    - funlen
+    - nestif
+
+  settings:
+    lll:
+      line-length: 120
+      tab-width: 4
+    gocyclo:
+      min-complexity: 10
+    gocognit:
+      min-complexity: 15
+    nestif:
+      min-complexity: 4
+    funlen:
+      lines: 70
+      statements: 40
+
+    gocritic:
+      enabled-tags:
+        - diagnostic
+        - style
+        - performance
+
+    revive:
+      enable-default-rules: true
+      rules:
+        - name: exported
+          disabled: true
+        - name: package-comments
+          disabled: true
+
+  exclusions:
+    generated: lax
+    rules:
+      - path: _test\.go
+        linters:
+          - errcheck
+          - gosec
+          - bodyclose
+          - prealloc
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

Makefile

@@ -0,0 +1,27 @@
+.PHONY: unit-test
+unit-test:
+	go test -v -race ./...
+
+.PHONY: lint
+lint:
+	golangci-lint run ./...
+
+.PHONY: tools
+tools:
+	go install github.com/yoheimuta/protolint/cmd/protolint@latest
+	go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
+	go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+	go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $$(go env GOPATH)/bin v2.12.0
+	@echo "checking protobuf compiler, if it fails follow guide at https://protobuf.dev/installation/"
+	@which -s protoc && echo OK || exit 1
+
+.PHONY: protolint
+protolint:
+	protolint .
+
+.PHONY: protobuf
+protobuf:
+	protoc --go_out=. --go_opt=paths=source_relative \
+               --go-grpc_out=. --go-grpc_opt=paths=source_relative \
+               proto/dns/v1/dns.proto

README.md

@@ -0,0 +1 @@
+package dns_manager

cmd/client/main.go

@@ -0,0 +1 @@
+package main

cmd/server/main.go

@@ -0,0 +1 @@
+package main

go.mod

@@ -0,0 +1,15 @@
+module github.com/ilindan-dev/dns-manager
+
+go 1.26.2
+
+require (
+	google.golang.org/grpc v1.81.0
+	google.golang.org/protobuf v1.36.11
+)
+
+require (
+	golang.org/x/net v0.51.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 // indirect
+)

go.sum

@@ -0,0 +1,38 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 h1:ggcbiqK8WWh6l1dnltU4BgWGIGo+EVYxCaAPih/zQXQ=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.0 h1:W3G9N3KQf3BU+YuCtGKJk0CmxQNbAISICD/9AORxLIw=
+google.golang.org/grpc v1.81.0/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

internal/adapters/cli/cobra.go

@@ -0,0 +1 @@
+package cli

internal/adapters/grpc/client.go

@@ -0,0 +1 @@
+package grpc

internal/adapters/grpc/server.go

@@ -0,0 +1 @@
+package grpc

internal/adapters/resolvconf/file.go

@@ -0,0 +1 @@
+package resolvconf

internal/core/domain/errors.go

@@ -0,0 +1,34 @@
+// Package domain defines domain-level sentinel errors used by the core
+// DNS manager logic. These exported error variables are intended for
+// callers to compare using errors.Is so semantics remain stable across
+// packages and versions.
+package domain
+
+import "errors"
+
+// Sentinel errors used across domain logic.
+var (
+	// ErrInvalidIP indicates the provided DNS server address has an invalid
+	// textual IP format (neither a valid IPv4 nor IPv6). Use when validating
+	// client input for AddDNSServer.
+	ErrInvalidIP = errors.New("invalid IP address format")
+
+	// ErrAlreadyExists signals an attempt to add a nameserver that is
+	// already present in the resolver configuration. Returning this allows
+	// callers to treat duplicate-add attempts as a recoverable, explicit
+	// condition instead of a generic success/failure.
+	ErrAlreadyExists = errors.New("DNS server already exists")
+
+	// ErrNotFound indicates the requested DNS server address was not found
+	// when attempting removal.
+	ErrNotFound = errors.New("DNS server not found")
+
+	// ErrPermissionDenied indicates the process lacks permissions to modify
+	// the resolver configuration (for example, writing /etc/resolv.conf).
+	ErrPermissionDenied = errors.New("permission denied while accessing resolver configuration")
+
+	// ErrIO represents an unexpected I/O error while reading or writing the
+	// resolver configuration. When returning ErrIO, wrap the underlying
+	// error with fmt.Errorf("%w") so callers can inspect the cause.
+	ErrIO = errors.New("I/O error while accessing resolver configuration")
+)

internal/core/ports/dnsmanager.go

@@ -0,0 +1,19 @@
+// Package ports defines the contracts that the core logic
+// requires to interact with external adapters.
+package ports
+
+import "context"
+
+// DNSManager defines a layer of use cases for managing DNS servers.
+type DNSManager interface {
+	// AddDNSServer checks the validity of the IP address and adds it to the configuration,
+	// if it is not already there.
+	AddDNSServer(ctx context.Context, address string) error
+
+	// RemoveDNSServer removes the IP address from the configuration.
+	// Should return an error if the address is not found.
+	RemoveDNSServer(ctx context.Context, address string) error
+
+	// ListDNSServers returns a list of current DNS servers, preserving the original order.
+	ListDNSServers(ctx context.Context) ([]string, error)
+}

internal/core/ports/resolvconf.go

@@ -0,0 +1,15 @@
+package ports
+
+import "context"
+
+// ResolvConf provides atomic operations for managing the system's resolver configuration.
+type ResolvConf interface {
+	// GetServers reads the configuration and returns the ordered list
+	// of currently configured nameserver IPs.
+	GetServers(ctx context.Context) ([]string, error)
+
+	// RewriteServers atomically replaces all existing nameservers with the provided list.
+	// The implementation MUST preserve all non-nameserver directives (e.g., search, options)
+	// and guarantee "all-or-nothing" execution to prevent configuration corruption.
+	RewriteServers(ctx context.Context, addresses []string) error
+}

internal/service/dns_manager.go

@@ -0,0 +1 @@
+package service