Makefile

SHELL := /usr/bin/env bash

# Defaults
PROJECT_NAME ?= llm-d-kv-cache
DEV_VERSION ?= 0.0.1
PROD_VERSION ?= 0.0.0
IMAGE_TAG_BASE ?= ghcr.io/llm-d/$(PROJECT_NAME)
IMG = $(IMAGE_TAG_BASE):$(DEV_VERSION)
NAMESPACE ?= hc4ai-operator

TARGETOS ?= $(shell go env GOOS)
TARGETARCH ?= $(shell go env GOARCH)

# Build metadata injected into the version package via -ldflags.
VERSION_PKG := github.com/llm-d/llm-d-kv-cache/version
GIT_COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null)
BUILD_REF ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo $(DEV_VERSION))
LDFLAGS := -X '$(VERSION_PKG).CommitSHA=$(GIT_COMMIT)' -X '$(VERSION_PKG).BuildRef=$(BUILD_REF)'

PYTHON_EXE := $(shell command -v python3.12 || command -v python3)

CONTAINER_TOOL := $(shell { command -v docker >/dev/null 2>&1 && echo docker; } || { command -v podman >/dev/null 2>&1 && echo podman; })

ifeq ($(CONTAINER_TOOL),)
$(error Neither docker nor podman is installed. Try: sudo apt install docker.io OR brew install docker)
endif
BUILDER := $(shell command -v buildah >/dev/null 2>&1 && echo buildah || echo $(CONTAINER_TOOL))
UDS_TOKENIZER_IMAGE ?= llm-d-uds-tokenizer:e2e-test
FS_BACKEND_NAME ?= llmd-fs-backend
FS_BACKEND_DEV_IMG ?= $(IMAGE_TAG_BASE)/$(FS_BACKEND_NAME):$(DEV_VERSION)
FS_BACKEND_DIR := kv_connectors/llmd_fs_backend
PVC_EVICTOR_DIR := kv_connectors/pvc_evictor
CPU_TEST_DIRS ?= $(FS_BACKEND_DIR)/tests/cpu $(PVC_EVICTOR_DIR)/tests
CPU_TEST_VENV_DIR := $(FS_BACKEND_DIR)/.venv
CPU_TEST_VENV_BIN := $(CPU_TEST_VENV_DIR)/bin

# go source files
SRC = $(shell find . -type f -name '*.go')

.PHONY: help
help: ## Print help
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)


##@ Precommit code checks
.PHONY: precommit lint lint-fix tidy-go copr-fix
precommit: tidy-go lint copr-fix

tidy-go:
	@echo "Tidying up go.mod and go.sum..."
	@go mod tidy

lint: check-ruff ## Run all linters (Go + Python)
	@echo "==== Running Go linting ===="
	@golangci-lint run
	@echo "==== Running Python linting (ruff) ===="
	@ruff check .

lint-fix: check-ruff ## Run ruff with auto-fix and formatting
	@echo "==== Running Python linting with auto-fix (ruff) ===="
	@ruff check --fix .
	@ruff format .

copr-fix:
	@echo "Adding copyright headers..."
	@docker run -i --rm -v $(shell pwd):/github/workspace apache/skywalking-eyes header fix

clang:
	@echo "Running clang-format..."
	@find kv_connectors -type f \( \
	    -name "*.cu" -o -name "*.cuh" -o \
	    -name "*.cc" -o -name "*.cpp" -o \
	    -name "*.hpp" -o -name "*.h" \
	\) -exec clang-format -i {} +


##@ Development

.PHONY: test
test: unit-test e2e-test ## Run all tests (unit + e2e)

.PHONY: unit-test
unit-test: unit-test-uds unit-test-cpu ## Run unit tests

.PHONY: unit-test-uds
unit-test-uds: check-go download-zmq ## Run unit tests
	@printf "\033[33;1m==== Running unit tests ====\033[0m\n"
	@go test -v ./pkg/...

.PHONY: cpu-test-install-deps
cpu-test-install-deps: ## Set up venv and install CPU test dependencies
	@printf "\033[33;1m==== Setting up CPU test venv ====\033[0m\n"
	@if [ ! -f "$(CPU_TEST_VENV_BIN)/python" ]; then \
		echo "Creating virtual environment in $(CPU_TEST_VENV_DIR)..."; \
		$(PYTHON_EXE) -m venv $(CPU_TEST_VENV_DIR); \
		echo "Upgrading pip..."; \
		$(CPU_TEST_VENV_BIN)/pip install --upgrade pip > /dev/null; \
	else \
		echo "Virtual environment already exists"; \
	fi
	@$(CPU_TEST_VENV_BIN)/pip install -q -r $(FS_BACKEND_DIR)/tests/requirements-cpu.txt

.PHONY: unit-test-cpu
unit-test-cpu: cpu-test-install-deps ## Run CPU-safe Python unit tests
	@printf "\033[33;1m==== Running CPU Python unit tests ====\033[0m\n"
	@$(CPU_TEST_VENV_BIN)/python -m pytest -q $(CPU_TEST_DIRS)

.PHONY: unit-test-race
unit-test-race: check-go download-zmq ## Run unit tests with Go race detector enabled
	@printf "\033[33;1m==== Running unit tests with race detector ====\033[0m\n"
	@go test -v -race -count=1 ./pkg/...

.PHONY: e2e-test
e2e-test: e2e-test-uds ## Run end-to-end tests

.PHONY: image-build-uds
image-build-uds: check-container-tool ## Build the UDS tokenizer container image
	@printf "\033[33;1m==== Building UDS tokenizer image $(UDS_TOKENIZER_IMAGE) ====\033[0m\n"
	$(CONTAINER_TOOL) build \
		--platform linux/$(TARGETARCH) \
		-t $(UDS_TOKENIZER_IMAGE) services/uds_tokenizer

.PHONY: e2e-test-uds
e2e-test-uds: check-go download-zmq image-build-uds ## Run UDS tokenizer e2e tests (requires Docker or Podman)
	@printf "\033[33;1m==== Running end-to-end tests (UDS tokenizer service) ====\033[0m\n"
	@if [ "$(CONTAINER_TOOL)" = "podman" ]; then \
		DOCKER_HOST="unix://$$XDG_RUNTIME_DIR/podman/podman.sock"; \
		export TESTCONTAINERS_RYUK_DISABLED=true; \
	else \
		DOCKER_HOST=$$(docker context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null); \
		if [ -z "$$DOCKER_HOST" ]; then \
			echo "ERROR: DOCKER_HOST could not be determined. Ensure Docker is installed and a context is configured."; \
			exit 1; \
		fi; \
		export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock; \
	fi; \
	DOCKER_HOST=$$DOCKER_HOST \
	UDS_TOKENIZER_IMAGE=$(UDS_TOKENIZER_IMAGE) \
	go test -v -count=1 -timeout 10m ./tests/e2e/uds_tokenizer/...
##@ UDS Tokenizer Python Tests

UDS_TOKENIZER_DIR := services/uds_tokenizer
UDS_TOKENIZER_VENV_DIR := $(UDS_TOKENIZER_DIR)/.venv
UDS_TOKENIZER_VENV_BIN := $(UDS_TOKENIZER_VENV_DIR)/bin

.PHONY: uds-tokenizer-install-deps
uds-tokenizer-install-deps: ## Set up venv and install UDS tokenizer dependencies
	@printf "\033[33;1m==== Setting up UDS tokenizer venv and dependencies ====\033[0m\n"
	@if [ ! -f "$(UDS_TOKENIZER_VENV_BIN)/python" ]; then \
		echo "Creating virtual environment in $(UDS_TOKENIZER_VENV_DIR)..."; \
		$(PYTHON_EXE) -m venv $(UDS_TOKENIZER_VENV_DIR); \
		echo "Upgrading pip..."; \
		$(UDS_TOKENIZER_VENV_BIN)/pip install --upgrade pip; \
	else \
		echo "Virtual environment already exists"; \
	fi
	@echo "Installing dependencies..."
	@$(UDS_TOKENIZER_VENV_BIN)/pip install "$(UDS_TOKENIZER_DIR)[test]" --extra-index-url https://download.pytorch.org/whl/cpu

.PHONY: uds-tokenizer-service-test
uds-tokenizer-service-test: uds-tokenizer-install-deps ## Run UDS tokenizer integration tests (starts server automatically)
	@printf "\033[33;1m==== Running UDS tokenizer integration tests ====\033[0m\n"
	@$(UDS_TOKENIZER_VENV_BIN)/python -m pytest \
		$(UDS_TOKENIZER_DIR)/tests/test_integration.py \
		$(UDS_TOKENIZER_DIR)/tests/test_renderer.py \
		-v --timeout=60

.PHONY: run
run: build-uds ## Run the application locally
	@printf "\033[33;1m==== Running application ====\033[0m\n"
	@./bin/$(PROJECT_NAME)

##@ Build

.PHONY: build
build: build-uds ## Build binary

.PHONY: build-uds
build-uds: check-go download-zmq ## Build
	@printf "\033[33;1m==== Building ====\033[0m\n"
	@go build ./pkg/...
	@mkdir -p bin
	@go build -ldflags "$(LDFLAGS)" -o bin/$(PROJECT_NAME) ./examples/kv_events/online
	@echo "✅ Build succeeded"

.PHONY:	image-build
image-build: check-container-tool load-version-json ## Build Docker image
	@printf "\033[33;1m==== Building Docker image $(IMG) ====\033[0m\n"
	$(CONTAINER_TOOL) build \
		--platform linux/$(TARGETARCH) \
		-t $(IMG) .
.PHONY: image-push
image-push: check-container-tool load-version-json ## Push Docker image $(IMG) to registry
	@printf "\033[33;1m==== Pushing Docker image $(IMG) ====\033[0m\n"
	$(CONTAINER_TOOL) push $(IMG)

##@ Install/Uninstall Targets

# Default install/uninstall (Docker)
install: install-docker ## Default install using Docker
	@echo "Default Docker install complete."
uninstall: uninstall-docker ## Default uninstall using Docker
	@echo "Default Docker uninstall complete."
### Docker Targets

.PHONY: install-docker
install-docker: check-container-tool ## Install app using $(CONTAINER_TOOL)
	@echo "Starting container with $(CONTAINER_TOOL)..."
	$(CONTAINER_TOOL) run -d --name $(PROJECT_NAME)-container $(IMG)
	@echo "$(CONTAINER_TOOL) installation complete."
	@echo "To use $(PROJECT_NAME), run:"
	@echo "alias $(PROJECT_NAME)='$(CONTAINER_TOOL) exec -it $(PROJECT_NAME)-container /app/$(PROJECT_NAME)'"

.PHONY: uninstall-docker
uninstall-docker: check-container-tool ## Uninstall app from $(CONTAINER_TOOL)
	@echo "Stopping and removing container in $(CONTAINER_TOOL)..."
	-$(CONTAINER_TOOL) stop $(PROJECT_NAME)-container && $(CONTAINER_TOOL) rm $(PROJECT_NAME)-container
	@echo "$(CONTAINER_TOOL) uninstallation complete. Remove alias if set: unalias $(PROJECT_NAME)"

### Kubernetes Targets (kubectl)

.PHONY: install-k8s
install-k8s: check-kubectl check-kustomize check-envsubst ## Install on Kubernetes
	export PROJECT_NAME=${PROJECT_NAME}
	export NAMESPACE=${NAMESPACE}
	@echo "Creating namespace (if needed) and setting context to $(NAMESPACE)..."
	kubectl create namespace $(NAMESPACE) 2>/dev/null || true
	kubectl config set-context --current --namespace=$(NAMESPACE)
	@echo "Deploying resources from deploy/ ..."
	# Build the kustomization from deploy, substitute variables, and apply the YAML
	kustomize build deploy | envsubst | kubectl apply -f -
	@echo "Waiting for pod to become ready..."
	sleep 5
	@POD=$$(kubectl get pod -l app=$(PROJECT_NAME)-statefulset -o jsonpath='{.items[0].metadata.name}'); \
	echo "Kubernetes installation complete."; \
	echo "To use the app, run:"; \
	echo "alias $(PROJECT_NAME)='kubectl exec -n $(NAMESPACE) -it $$POD -- /app/$(PROJECT_NAME)'"

.PHONY: uninstall-k8s
uninstall-k8s: check-kubectl check-kustomize check-envsubst ## Uninstall from Kubernetes
	export PROJECT_NAME=${PROJECT_NAME}
	export NAMESPACE=${NAMESPACE}
	@echo "Removing resources from Kubernetes..."
	kustomize build deploy | envsubst | kubectl delete --force -f - || true
	POD=$$(kubectl get pod -l app=$(PROJECT_NAME)-statefulset -o jsonpath='{.items[0].metadata.name}'); \
	echo "Deleting pod: $$POD"; \
	kubectl delete pod "$$POD" --force --grace-period=0 || true; \
	echo "Kubernetes uninstallation complete. Remove alias if set: unalias $(PROJECT_NAME)"

### OpenShift Targets (oc)

.PHONY: install-openshift
install-openshift: check-kubectl check-kustomize check-envsubst ## Install on OpenShift
	exit 0

.PHONY: uninstall-openshift
uninstall-openshift: check-kubectl check-kustomize check-envsubst ## Uninstall from OpenShift
	exit 0

### RBAC Targets (using kustomize and envsubst)

.PHONY: install-rbac
install-rbac: check-kubectl check-kustomize check-envsubst ## Install RBAC
	@echo "Applying RBAC configuration from deploy/rbac..."
	kustomize build deploy/rbac | envsubst '$$PROJECT_NAME $$NAMESPACE $$IMAGE_TAG_BASE $$VERSION' | kubectl apply -f -

.PHONY: uninstall-rbac
uninstall-rbac: check-kubectl check-kustomize check-envsubst ## Uninstall RBAC
	@echo "Removing RBAC configuration from deploy/rbac..."
	kustomize build deploy/rbac | envsubst '$$PROJECT_NAME $$NAMESPACE $$IMAGE_TAG_BASE $$VERSION' | kubectl delete -f - || true

##@ Version Extraction
.PHONY: version dev-registry prod-registry extract-version-info

dev-version: check-jq
	@jq -r '.dev-version' .version.json

prod-version: check-jq
	@jq -r '.prod-version' .version.json

dev-registry: check-jq
	@jq -r '."dev-registry"' .version.json

prod-registry: check-jq
	@jq -r '."prod-registry"' .version.json

extract-version-info: check-jq
	@echo "DEV_VERSION=$$(jq -r '."dev-version"' .version.json)"
	@echo "PROD_VERSION=$$(jq -r '."prod-version"' .version.json)"
	@echo "DEV_IMAGE_TAG_BASE=$$(jq -r '."dev-registry"' .version.json)"
	@echo "PROD_IMAGE_TAG_BASE=$$(jq -r '."prod-registry"' .version.json)"

##@ Load Version JSON

.PHONY: load-version-json
load-version-json: check-jq
	@if [ "$(DEV_VERSION)" = "0.0.1" ]; then \
	  DEV_VERSION=$$(jq -r '."dev-version"' .version.json); \
	  PROD_VERSION=$$(jq -r '."dev-version"' .version.json); \
	  echo "Loaded DEV_VERSION from .version.json: $$DEV_VERSION"; \
	  echo "Loaded PROD_VERSION from .version.json: $$PROD_VERSION"; \
	  export DEV_VERSION; \
	  export PROD_VERSION; \
	fi && \
	CURRENT_DEFAULT="ghcr.io/llm-d/$(PROJECT_NAME)"; \
	if [ "$(IMAGE_TAG_BASE)" = "$$CURRENT_DEFAULT" ]; then \
	  IMAGE_TAG_BASE=$$(jq -r '."dev-registry"' .version.json); \
	  echo "Loaded IMAGE_TAG_BASE from .version.json: $$IMAGE_TAG_BASE"; \
	  export IMAGE_TAG_BASE; \
	fi && \
	echo "Final values: DEV_VERSION=$$DEV_VERSION, PROD_VERSION=$$PROD_VERSION, IMAGE_TAG_BASE=$$IMAGE_TAG_BASE"

.PHONY: env
env: load-version-json ## Print environment variables
	@echo "DEV_VERSION=$(DEV_VERSION)"
	@echo "PROD_VERSION=$(PROD_VERSION)"
	@echo "IMAGE_TAG_BASE=$(IMAGE_TAG_BASE)"
	@echo "IMG=$(IMG)"
	@echo "CONTAINER_TOOL=$(CONTAINER_TOOL)"

##@ Tools

.PHONY: check-tools
check-tools: \
  check-go \
  check-ginkgo \
  check-golangci-lint \
  check-jq \
  check-kustomize \
  check-envsubst \
  check-container-tool \
  check-kubectl \
  check-builder \
  check-podman
	@echo "All required tools are installed."
.PHONY: check-go
check-go:
	@command -v go >/dev/null 2>&1 || { \
	  echo "Go is not installed. Install it from https://golang.org/dl/"; exit 1; }

.PHONY: check-ginkgo
check-ginkgo:
	@command -v ginkgo >/dev/null 2>&1 || { \
	  echo "ginkgo is not installed. Install with: go install github.com/onsi/ginkgo/v2/ginkgo@latest"; exit 1; }

.PHONY: check-golangci-lint
check-golangci-lint:
	@command -v golangci-lint >/dev/null 2>&1 || { \
	  echo "golangci-lint is not installed. Install from https://golangci-lint.run/docs/welcome/install/"; exit 1; }

.PHONY: check-jq
check-jq:
	@command -v jq >/dev/null 2>&1 || { \
	  echo "jq is not installed. Install it from https://stedolan.github.io/jq/download/"; exit 1; }

.PHONY: check-kustomize
check-kustomize:
	@command -v kustomize >/dev/null 2>&1 || { \
	  echo "kustomize is not installed. Install it from https://kubectl.docs.kubernetes.io/installation/kustomize/"; exit 1; }

.PHONY: check-envsubst
check-envsubst:
	@command -v envsubst >/dev/null 2>&1 || { \
	  echo "envsubst is not installed. It is part of gettext."; \
	  echo "Try: sudo apt install gettext OR brew install gettext"; exit 1; }

.PHONY: check-container-tool
check-container-tool:
	@command -v $(CONTAINER_TOOL) >/dev/null 2>&1 || { \
	  echo "$(CONTAINER_TOOL) is not installed."; \
	  echo "Try: sudo apt install $(CONTAINER_TOOL) OR brew install $(CONTAINER_TOOL)"; exit 1; }

.PHONY: check-kubectl
check-kubectl:
	@command -v kubectl >/dev/null 2>&1 || { \
	  echo "kubectl is not installed. Install it from https://kubernetes.io/docs/tasks/tools/"; exit 1; }

.PHONY: check-builder
check-builder:
	@if [ -z "$(BUILDER)" ]; then \
		echo "No container builder tool (buildah, docker, or podman) found."; \
		exit 1; \
	else \
		echo "Using builder: $(BUILDER)"; \
	fi

.PHONY: check-podman
check-podman:
	@command -v podman >/dev/null 2>&1 || { \
	  echo "Podman is not installed. You can install it with:"; \
	  echo "sudo apt install podman  OR  brew install podman"; exit 1; }

.PHONY: check-ruff
check-ruff:
	@command -v ruff >/dev/null 2>&1 || { \
	  echo "ruff is not installed. Installing..."; \
	  pip install ruff; \
	}

##@ Alias checking
.PHONY: check-alias
check-alias: check-container-tool
	@echo "Checking alias functionality for container '$(PROJECT_NAME)-container'..."
	@if ! $(CONTAINER_TOOL) exec $(PROJECT_NAME)-container /app/$(PROJECT_NAME) --help >/dev/null 2>&1; then \
	  echo "The container '$(PROJECT_NAME)-container' is running, but the alias might not work."; \
	  echo "Try: $(CONTAINER_TOOL) exec -it $(PROJECT_NAME)-container /app/$(PROJECT_NAME)"; \
	else \
	  echo "Alias is likely to work: alias $(PROJECT_NAME)='$(CONTAINER_TOOL) exec -it $(PROJECT_NAME)-container /app/$(PROJECT_NAME)'"; \
	fi

.PHONY: print-namespace
print-namespace: ## Print the current namespace
	@echo "$(NAMESPACE)"

.PHONY: print-project-name
print-project-name: ## Print the current project name
	@echo "$(PROJECT_NAME)"

.PHONY: clean
clean: ## Clean build artifacts
	@printf "\033[33;1m==== Cleaning build artifacts ====\033[0m\n"
	@rm -rf build/
	@echo "Build artifacts cleaned."

.PHONY: install-hooks
install-hooks: ## Install git hooks
	git config core.hooksPath hooks

##@ gRPC Code Generation

.PHONY: generate-grpc-go
generate-grpc-go: check-protoc ## Generate gRPC code from protobuf definitions for Go client
	@echo "Generating gRPC code from protobuf definitions for Go client..."
	@mkdir -p api/tokenizerpb api/indexerpb
	@protoc --go_out=. --go-grpc_out=. --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative api/tokenizerpb/tokenizer.proto
	@protoc --go_out=. --go-grpc_out=. --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative api/indexerpb/indexer.proto
	@echo "✅ gRPC Go code generated successfully"

.PHONY: generate-grpc-python
generate-grpc-python: check-grpc-tools ## Generate gRPC code from protobuf definitions for Python server
	@echo "Generating gRPC code from protobuf definitions for Python server..."
	@mkdir -p services/uds_tokenizer/tokenizerpb
	@$(UDS_TOKENIZER_VENV_BIN)/python -m grpc_tools.protoc -Iapi --python_out=services/uds_tokenizer --grpc_python_out=services/uds_tokenizer api/tokenizerpb/tokenizer.proto
	@echo "✅ gRPC Python code generated successfully"

.PHONY: generate-grpc
generate-grpc: generate-grpc-go generate-grpc-python ## Generate gRPC code for both client and server

# Ensure protoc is available before generating gRPC code
.PHONY: check-protoc
check-protoc:
	@command -v protoc >/dev/null 2>&1 || { \
	  echo "protoc is not installed. Install it from https://grpc.io/docs/protoc-installation/"; exit 1; }

# Ensure grpc_tools is available before generating gRPC Python code
.PHONY: check-grpc-tools
check-grpc-tools: uds-tokenizer-install-deps
	@echo "Checking if grpc_tools is installed..."
	@if ! $(UDS_TOKENIZER_VENV_BIN)/python -c "import grpc_tools" 2>/dev/null; then \
	  echo "grpc_tools is not installed. Installing from requirements..."; \
	  $(UDS_TOKENIZER_VENV_BIN)/pip install grpcio-tools; \
	fi
	@echo "✅ grpc_tools is available"


##@ ZMQ Setup

.PHONY: download-zmq
download-zmq: ## Install ZMQ dependencies based on OS/ARCH
	@echo "Checking if ZMQ is already installed..."
	@if pkg-config --exists libzmq; then \
	  echo "✅ ZMQ is already installed."; \
	else \
	  echo "Installing ZMQ dependencies..."; \
	  if [ "$(TARGETOS)" = "linux" ]; then \
	    if [ -x "$$(command -v apt)" ]; then \
	      apt update && apt install -y libzmq3-dev pkg-config; \
	    elif [ -x "$$(command -v dnf)" ]; then \
	      dnf install -y zeromq-devel pkgconfig; \
	    else \
	      echo "Unsupported Linux package manager. Install libzmq manually."; \
	      exit 1; \
	    fi; \
	  elif [ "$(TARGETOS)" = "darwin" ]; then \
	    if [ -x "$$(command -v brew)" ]; then \
	      brew install zeromq pkg-config; \
	    else \
	      echo "Homebrew is not installed and is required to install zeromq. Install it from https://brew.sh/"; \
	      exit 1; \
	    fi; \
	  else \
	    echo "Unsupported OS: $(TARGETOS). Install libzmq manually - check https://zeromq.org/download/ for guidance."; \
	    exit 1; \
	  fi; \
	  echo "✅ ZMQ dependencies installed."; \
	fi


##@ Examples

UDS_TOKENIZER_GRPC_PORT ?= 50051
UDS_TOKENIZER_HEALTH_PORT ?= 8082

# Define a template for building examples
define BUILD_EXAMPLE_TEMPLATE
$(1): $$(SRC) | check-go
	@echo "Building $$@..."
	@mkdir -p $$(dir $$@)
	@go build -ldflags "$(LDFLAGS)" -o $$@ $(2)
	@echo "✅ Built $$@"
endef

# Generate build rules for simple examples (single main.go)
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/offline,examples/kv_events/offline/main.go))
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/online,examples/kv_events/online/main.go))
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/valkey,examples/valkey_example/main.go))
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/kv_cache_index,examples/kv_cache_index/main.go))
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/kv_cache_index_service/client,examples/kv_cache_index_service/client/main.go))
$(eval $(call BUILD_EXAMPLE_TEMPLATE,bin/examples/kv_cache_index_service/server,./examples/kv_cache_index_service/server))

.PHONY: build-examples
build-examples: bin/examples/offline bin/examples/online bin/examples/valkey bin/examples/kv_cache_index bin/examples/kv_cache_index_service/server bin/examples/kv_cache_index_service/client ## Build all example binaries
	@echo "✅ All examples built successfully!"

# Allow passing the example binary as a positional make goal, e.g.
#   make run-example offline
# If a positional example goal is provided, use it; otherwise fall back to default.
EXAMPLE_FROM_GOALS := $(word 2,$(MAKECMDGOALS))
ifeq ($(EXAMPLE_FROM_GOALS),)
EXAMPLE ?= bin/examples/offline
else
EXAMPLE := bin/examples/$(EXAMPLE_FROM_GOALS)
endif

# Allow short example names to appear on the command line without being
# interpreted as missing targets.
EXAMPLE_SHORTS := offline online valkey kv_cache_index kv_cache_index_service
.PHONY: $(EXAMPLE_SHORTS)
$(EXAMPLE_SHORTS):

.PHONY: start-tokenizer
start-tokenizer: check-container-tool ## Start the UDS tokenizer container; requires image-build-uds to have been run first
	@printf "\033[33;1m==== Starting UDS tokenizer container ====\033[0m\n"
	@$(CONTAINER_TOOL) run -d --rm --name uds-tokenizer-example --network host \
		-e GRPC_PORT=$(UDS_TOKENIZER_GRPC_PORT) \
		-e PROBE_PORT=$(UDS_TOKENIZER_HEALTH_PORT) \
		$(UDS_TOKENIZER_IMAGE)
	@printf "Waiting for tokenizer to be ready"
	@for i in $$(seq 1 30); do \
		if curl -sf http://localhost:$(UDS_TOKENIZER_HEALTH_PORT)/healthz > /dev/null 2>&1; then \
			printf " ready!\n"; break; \
		fi; \
		if [ $$i -eq 30 ]; then \
			printf " timeout!\n"; \
			$(CONTAINER_TOOL) stop uds-tokenizer-example 2>/dev/null || true; \
			exit 1; \
		fi; \
		printf "."; sleep 2; \
	done

.PHONY: stop-tokenizer
stop-tokenizer: ## Stop and remove the UDS tokenizer container
	@$(CONTAINER_TOOL) stop uds-tokenizer-example 2>/dev/null || true
	@$(CONTAINER_TOOL) rm -f uds-tokenizer-example 2>/dev/null || true

.PHONY: run-example-only
run-example-only: $(EXAMPLE) ## Run the example binary only (tokenizer must already be running via start-tokenizer)
	@printf "\033[33;1m==== Running example $(EXAMPLE) ====\033[0m\n"
	@TOKENIZER_ENDPOINT=localhost:$(UDS_TOKENIZER_GRPC_PORT) ./$(EXAMPLE)

.PHONY: run-example
run-example: ## Run the example with UDS tokenizer in Docker (e.g., make run-example offline); requires image-build-uds to have been run first
	@$(MAKE) --no-print-directory start-tokenizer
	@$(MAKE) --no-print-directory run-example-only; status=$$?; \
		$(MAKE) --no-print-directory stop-tokenizer; \
		exit $$status

.PHONY: image-fs-backend-build
image-fs-backend-build: check-container-tool load-version-json ## Build the development container for the llmd_fs_backend connector
	@printf "\033[33;1m==== Building development container $(FS_BACKEND_DEV_IMG) ====\033[0m\n"
	$(CONTAINER_TOOL) build \
		--platform linux/$(TARGETARCH) \
		-f kv_connectors/llmd_fs_backend/Dockerfile.dev \
		-t $(FS_BACKEND_DEV_IMG) .

.PHONY: image-fs-backend-push
image-fs-backend-push: check-container-tool load-version-json ## Push the development container for the llmd_fs_backend connector
	@printf "\033[33;1m==== Pushing development container $(FS_BACKEND_DEV_IMG) ====\033[0m\n"
	$(CONTAINER_TOOL) push $(FS_BACKEND_DEV_IMG)