Nail/sless
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync all documentation for agent handoff (v0.1.34 + funcs-service v0.2.0)

Browse Source
This commit is contained in:
Naeel
2026-03-18 20:19:48 +03:00
parent a04dfb2d0c
commit 2c194f6a7f
6 changed files with 481 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/architecture/project-structure.md
+90 -33
View File
@@ -1,49 +1,106 @@
# Структура проекта
Последнее обновление: 2026-03-18 (v0.1.34)
## Репозиторий
`gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless`
## Директории
## Директории (актуальное состояние)
```
sless/
├── cmd/
│ └── api/
│ └── main.go # точка входа API сервера
├── main.go # точка входа оператора (controller-runtime + HTTP сервер)
├── Dockerfile # multi-stage сборка оператора
├── go.mod # module: gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless
├── Makefile
├── api/
│ └── v1alpha1/ # CRD типы для controller-gen
│ ├── function_types.go # Function CRD: spec, status
│ ├── job_types.go # FunctionJob CRD
│ ├── trigger_types.go # Trigger CRD
│ └── zz_generated.deepcopy.go # автогенерация DeepCopy
├── controllers/
│ ├── function_controller.go # Function → kaniko Job → Deployment/Service
│ ├── functionjob_controller.go # FunctionJob → k8s Job → stdout/stderr → status
│ └── trigger_controller.go # Trigger → Deployment scale / CronJob
├── internal/
│ ├── api/
│ │ ├── handler/ # HTTP хендлеры (functions, versions, triggers)
│ │ ├── middleware/ # auth, logging, rate limit
│ │ └── router.go # регистрация маршрутов
│ ├── model/ # доменные модели: Function, Version, Trigger, Invocation
│ │ ├── router.go # gorilla/mux: регистрация всех маршрутов
│ │ ├── middleware/
│ │ │ ├── auth.go # JWT Bearer → namespace (SHA256)
│ │ │ └── logging.go # access log
│ │ └── handler/
│ │ ├── handler.go # Handler struct (K8s, S3, PG, Log)
│ │ ├── functions.go # GET/POST/PUT/DELETE функций
│ │ ├── triggers.go # GET/POST/PATCH/DELETE триггеров
│ │ ├── upload.go # POST /upload: zip → tar.gz → S3 → CRD patch
│ │ ├── source.go # GET /source: S3 tar.gz → JSON файлы (НОВЫЙ v0.1.34)
│ │ ├── jobs.go # GET/POST/DELETE FunctionJob
│ │ ├── invocations.go # GET /invocations: логи из Postgres
│ │ ├── invoke.go # прокси HTTP вызовов функций
│ │ └── namespace.go # POST /ensure: создать k8s namespace
│ ├── builder/
│ │ └── context.go # zip + runtime → tar.gz + Dockerfile для kaniko
│ ├── storage/
│ │ ├── postgres/ # CRUD функций, версий, логов вызовов
│ │ └── s3/ # загрузка/скачивание zip архивов кода
│ ├── builder/ # сборка Docker образа из кода пользователя
│ ├── runner/ # запуск функций в k8s (Jobs / Deployments)
│ └── config/ # конфиг из env переменных
├── migrations/ # SQL миграции (numbered: 001_, 002_, ...)
├── deployments/
│ └── k8s/ # манифесты: Deployment, Service, Ingress, RBAC
├── api/
│ └── openapi.yaml # OpenAPI 3.0 спецификация
├── doc/ # документация проекта (эта папка)
└── docker-compose.yml # локальная разработка: postgres, redis, minio
│ │ ├── s3/client.go # minio-go: Upload, UploadContext, Download, Delete
│ │ └── postgres/ # хранение invocation logs
│ └── config/ # конфиг из env переменных
├── services/
│ └── funcs/ # отдельный HTTP сервис (web-консоль)
│ ├── main.go # v0.2.0: HTML+plain text+proxy к оператору
│ ├── index.html # dark-themed HTML консоль (go:embed)
│ ├── Dockerfile # multi-stage Go → alpine (копирует main.go + index.html)
│ └── go.mod # отдельный Go модуль
├── migrations/
│ └── 001_initial.sql # схема PostgreSQL (invocation logs)
├── deployments/k8s/
│ ├── operator.yaml # ConfigMap + Deployment + Service + Ingress оператора
│ ├── funcs-service.yaml # Deployment + Service + Ingress funcs-service
│ ├── postgres.yaml # PostgreSQL
│ └── rbac.yaml # ClusterRole + ClusterRoleBinding для оператора
├── runtimes/
│ ├── python3.11/server.py # HTTP wrapper (str → text/plain начиная с v0.1.3)
│ ├── nodejs20/server.js # HTTP wrapper
│ └── go1.23/ # multi-stage builder образ
├── terraform/
│ └── provider/ # terraform-provider-sless (отдельный Go модуль)
│ ├── main.go
│ └── internal/
│ ├── client/client.go # REST клиент к оператору
│ ├── resources/
│ │ ├── function_resource.go # sless_function: source_dir, code_hash, ModifyPlan
│ │ ├── trigger_resource.go # sless_trigger
│ │ └── job_resource.go # sless_job + ErrJobAlreadyExists
│ └── provider/provider.go
├── examples/
│ ├── POSTGRES/ # pg функции: create-table, pg-info, pg-table-reader
│ ├── hello-go/
│ ├── hello-node/
│ └── simple-python/
├── config/ # kustomize конфиги (controller-gen артефакты)
│ ├── crd/ # CRD манифесты (автогенерация)
│ ├── rbac/
│ └── samples/
├── hack/
│ └── boilerplate.go.txt # шаблон заголовков файлов
└── doc/ # документация проекта
├── architecture/
│ ├── agent-handoff-2026-03-18.md # полный контекст для нового агента
│ ├── overview.md # архитектура системы
│ └── project-structure.md # этот файл
├── api/design.md # дизайн REST API
├── decisions/log.md # журнал архитектурных решений
├── errors/log.md # известные ошибки и решения
└── progress.md # трекер задач
```
## Go module
## Go модули
```
module gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless
```
Два независимых Go модуля в одном репозитории:
## Порядок разработки
1. `internal/config` + `internal/model` — базовые структуры данных
2. `migrations/` + `internal/storage/postgres` — схема БД и CRUD
3. `internal/api` — HTTP хендлеры, роутер, middleware
4. `internal/storage/s3` — загрузка кода функций
5. `internal/builder` — сборка Docker образов
6. `internal/runner` — запуск функций в k8s
7. `deployments/k8s` — манифесты для деплоя
| Модуль | Путь | Назначение |
|--------|------|-----------|
| `gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless` | `/` | Оператор + API |
| `gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless/services/funcs` | `services/funcs/` | Web-консоль сервис |
| `terra.k8c.ru/naeel/sless` | `terraform/provider/` | Terraform провайдер |