From b2d3358ac3e0225909f81936940fc851580f2f44 Mon Sep 17 00:00:00 2001 From: xt <1014797089@qq.com> Date: Sun, 21 Jun 2026 12:57:41 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(runtime):=20=E6=B7=BB=E5=8A=A0gRPC?= =?UTF-8?q?=E6=8B=A6=E6=88=AA=E5=99=A8=E5=AE=9E=E7=8E=B0=E8=AE=A4=E8=AF=81?= =?UTF-8?q?=E5=92=8C=E5=8F=AF=E8=A7=82=E6=B5=8B=E6=80=A7=E5=8A=9F=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 实现了认证拦截器支持统一认证和授权功能 - 添加了可观测性拦截器包括日志、追踪、指标收集等功能 - 集成了超时控制、熔断器和限流器中间件支持 - 提供了完整的客户端和服务端拦截器链式调用机制 - 实现了上下文传递和元数据处理功能 - 添加了gRPC方法级别的权限控制和租户支持 --- contract | 2 +- core | 2 +- runtime/grpc | 2 +- runtime/http | 2 +- runtime/worker | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/contract b/contract index 982786b..a4f36a6 160000 --- a/contract +++ b/contract @@ -1 +1 @@ -Subproject commit 982786b0fc77e8196141bd2c8bc84df3d221e539 +Subproject commit a4f36a63dc933fd792ae6e72269c184387f13f60 diff --git a/core b/core index 8caed2e..3c37082 160000 --- a/core +++ b/core @@ -1 +1 @@ -Subproject commit 8caed2e9a0c13963d445315b152f9613fe445298 +Subproject commit 3c37082c20c002d0fef7a533a335be8e9518e43f diff --git a/runtime/grpc b/runtime/grpc index 2073b58..01e00d1 160000 --- a/runtime/grpc +++ b/runtime/grpc @@ -1 +1 @@ -Subproject commit 2073b58c3936069d2deeda087b9243526517da48 +Subproject commit 01e00d1fb8ee0c4405afc032bc60532a43e80641 diff --git a/runtime/http b/runtime/http index 225ca98..fe35dc3 160000 --- a/runtime/http +++ b/runtime/http @@ -1 +1 @@ -Subproject commit 225ca98f40d732c7c0f22db4a02bb9eb0ce9b217 +Subproject commit fe35dc3c0bfc426d47dcaec5bcf0cb8d6d9f6377 diff --git a/runtime/worker b/runtime/worker index 57c4d7c..4093ccf 160000 --- a/runtime/worker +++ b/runtime/worker @@ -1 +1 @@ -Subproject commit 57c4d7cc015c86c912798224eb25ed1f9d1ea106 +Subproject commit 4093ccf0cb820e5c89f9db5f30b4151c67547e6d From 5f46dd89a37e97016f4383ddaa5cb5abaad196da Mon Sep 17 00:00:00 2001 From: xt <1014797089@qq.com> Date: Sun, 21 Jun 2026 13:27:05 +0800 Subject: [PATCH 2/2] chore: publish alpha module release chain --- README.md | 3 + bridge | 2 +- cap | 2 +- cmd/nucleus/internal/initcmd/command_test.go | 4 +- cmd/nucleus/internal/initcmd/constants.go | 6 +- cmd/nucleus/internal/initcmd/templates.go | 38 +++++++-- cmd/nucleus/internal/repair/repair_test.go | 12 ++- docs/implementation-status.md | 89 ++++++++++++++++++++ examples/service/README.md | 17 +++- go.mod | 6 +- go.sum | 2 + runtime/grpc | 2 +- runtime/http | 2 +- runtime/worker | 2 +- 14 files changed, 164 insertions(+), 23 deletions(-) create mode 100644 docs/implementation-status.md diff --git a/README.md b/README.md index 8cd7d37..250e723 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ It is designed for AI agents, CI systems, and human reviewers to work from the s > Status: pre-alpha. The public repository is being prepared for the first source import under `github.com/nucleuskit/nucleus`. +For a code-level view of what is implemented, what is scaffold-only, and the +current module release status, see [Implementation Status](docs/implementation-status.md). + ## Why Nucleus Traditional Go microservice frameworks are optimized for humans writing code inside an IDE. Nucleus is optimized for AI agents changing services safely and repeatably. diff --git a/bridge b/bridge index 1995d48..2549645 160000 --- a/bridge +++ b/bridge @@ -1 +1 @@ -Subproject commit 1995d48409b3de91b0a0d15c0c0b4b5738487326 +Subproject commit 25496459a325018be4a0f22621db136b5ac6fc4c diff --git a/cap b/cap index 66253af..eb1efac 160000 --- a/cap +++ b/cap @@ -1 +1 @@ -Subproject commit 66253af2e343839c67348f73465cd2f92513575a +Subproject commit eb1efac82a1cb7d16e182f1fe38286720b65f3b5 diff --git a/cmd/nucleus/internal/initcmd/command_test.go b/cmd/nucleus/internal/initcmd/command_test.go index 576a9ad..0f7f01e 100644 --- a/cmd/nucleus/internal/initcmd/command_test.go +++ b/cmd/nucleus/internal/initcmd/command_test.go @@ -23,7 +23,9 @@ func TestCommandServiceTemplateProducesVerifiableProject(t *testing.T) { assertContains(t, output.Files, "nucleus.yaml") assertContains(t, output.Files, "contract/gen/.nucleus-source.sha256") assertContains(t, output.Files, "internal/adapter/http/gen/.nucleus-source.sha256") - assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7") + assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/http v0.1.0-alpha.2") + assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/cap v0.1.0-alpha.2 // indirect") + assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/core v0.1.0-alpha.2 // indirect") assertFileNotContains(t, dir, "go.mod", "replace ") assertFileNotContains(t, dir, "api/errors.yaml", "code: 0") assertFileContains(t, dir, "internal/adapter/http/gen/routes.gen.go", `runtimehttp "github.com/nucleuskit/http"`) diff --git a/cmd/nucleus/internal/initcmd/constants.go b/cmd/nucleus/internal/initcmd/constants.go index 556d2e1..899975e 100644 --- a/cmd/nucleus/internal/initcmd/constants.go +++ b/cmd/nucleus/internal/initcmd/constants.go @@ -32,7 +32,11 @@ const ( resultKindInit = "nucleus.init_result" nucleusHTTPModule = "github.com/nucleuskit/http" - nucleusHTTPVersion = "v0.1.0-alpha.1.0.20260615170339-225ca98f40d7" + nucleusHTTPVersion = "v0.1.0-alpha.2" + nucleusCapModule = "github.com/nucleuskit/cap" + nucleusCapVersion = "v0.1.0-alpha.2" + nucleusCoreModule = "github.com/nucleuskit/core" + nucleusCoreVersion = "v0.1.0-alpha.2" contractGenTarget = "contract/gen" httpAdapterGenTarget = "internal/adapter/http/gen" generatedFreshnessFile = ".nucleus-source.sha256" diff --git a/cmd/nucleus/internal/initcmd/templates.go b/cmd/nucleus/internal/initcmd/templates.go index 50a077e..5ea2cc0 100644 --- a/cmd/nucleus/internal/initcmd/templates.go +++ b/cmd/nucleus/internal/initcmd/templates.go @@ -20,9 +20,14 @@ func templateFiles(templateType string, name string, module string) (map[string] } func serviceTemplateFiles(name string, module string) map[string]string { + runtimeRequirements := []moduleRequirement{ + {Path: nucleusHTTPModule, Version: nucleusHTTPVersion}, + {Path: nucleusCapModule, Version: nucleusCapVersion, Indirect: true}, + {Path: nucleusCoreModule, Version: nucleusCoreVersion, Indirect: true}, + } return map[string]string{ - "go.mod": goModTemplate(module, []moduleRequirement{{Path: nucleusHTTPModule, Version: nucleusHTTPVersion}}), - "go.sum": goSumTemplate([]string{nucleusHTTPModule}), + "go.mod": goModTemplate(module, runtimeRequirements), + "go.sum": goSumTemplate([]string{nucleusHTTPModule, nucleusCapModule, nucleusCoreModule}), "nucleus.yaml": serviceManifestTemplate(name), "api/openapi.yaml": openAPITemplate(name), "api/errors.yaml": serviceErrorsTemplate(), @@ -75,8 +80,9 @@ func libraryTemplateFiles(name string, module string) map[string]string { } type moduleRequirement struct { - Path string - Version string + Path string + Version string + Indirect bool } func goModTemplate(module string, requires []moduleRequirement) string { @@ -88,21 +94,35 @@ func goModTemplate(module string, requires []moduleRequirement) string { } if len(requires) == 1 { item := requires[0] - builder.WriteString("\nrequire " + item.Path + " " + item.Version + "\n") + builder.WriteString("\nrequire " + formatModuleRequirement(item) + "\n") return builder.String() } builder.WriteString("\nrequire (\n") for _, item := range requires { - builder.WriteString("\t" + item.Path + " " + item.Version + "\n") + builder.WriteString("\t" + formatModuleRequirement(item) + "\n") } builder.WriteString(")\n") return builder.String() } +func formatModuleRequirement(item moduleRequirement) string { + line := item.Path + " " + item.Version + if item.Indirect { + line += " // indirect" + } + return line +} + func goSumTemplate(modules []string) string { entries := map[string]string{ - nucleusHTTPModule: `github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7 h1:wWoSiKv5HihOSOstvkov883PfSKLveAuW3tTZb9dH/Q= -github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7/go.mod h1:M4WW38dQuFNIm2kf1O5JIrat+KKZ3ONarUyrtbMDmJo= + nucleusHTTPModule: `github.com/nucleuskit/http v0.1.0-alpha.2 h1:YedMdKWg/YkouBOHu3hQvi4Vd8S6YNbdJFPUrzja+Og= +github.com/nucleuskit/http v0.1.0-alpha.2/go.mod h1:SxCsV2Ag3rtX82BbyIGN7ByiioUePbesFbIKIQQbeRs= +`, + nucleusCapModule: `github.com/nucleuskit/cap v0.1.0-alpha.2 h1:UnBp5ezoi+UrgT92DwpTdQynrEnUNnsf3rQKB0pNfPw= +github.com/nucleuskit/cap v0.1.0-alpha.2/go.mod h1:DLSQmS/6irYQfpWGJjce9+STvqG33yZMCxkwvdLf7XM= +`, + nucleusCoreModule: `github.com/nucleuskit/core v0.1.0-alpha.2 h1:CT4RJvCYtVNo0+Gqyf5zx4T90dBiXq4JVhQxEKBXyJ8= +github.com/nucleuskit/core v0.1.0-alpha.2/go.mod h1:fwIlIS28wLh/VQ/jhR4TgrZcrN1nOgrAxSYYYWRdEYk= `, } var builder strings.Builder @@ -292,7 +312,7 @@ func New(cfg config.Config) *App { return &App{ config: cfg, router: router, - server: serverpkg.NewHTTPServer(cfg.Server.Addr, router), + server: serverpkg.NewHTTPServer(cfg.Server.Addr, router.Handler()), } } diff --git a/cmd/nucleus/internal/repair/repair_test.go b/cmd/nucleus/internal/repair/repair_test.go index b6ae2f0..de1595a 100644 --- a/cmd/nucleus/internal/repair/repair_test.go +++ b/cmd/nucleus/internal/repair/repair_test.go @@ -20,7 +20,12 @@ ai: capabilities: - http `) - writeFile(t, dir, "go.mod", "module example.com/demo\n\ngo 1.26.3\n\nrequire github.com/nucleuskit/http v0.0.0\n\nreplace github.com/nucleuskit/http => "+runtimeHTTPReplace(t)+"\n") + writeFile(t, dir, "go.mod", "module example.com/demo\n\ngo 1.26.3\n\nrequire github.com/nucleuskit/http v0.0.0\n\nrequire (\n\tgithub.com/nucleuskit/cap v0.1.0-alpha.2 // indirect\n\tgithub.com/nucleuskit/core v0.1.0-alpha.2 // indirect\n)\n\n"+localRuntimeReplace(t)) + writeFile(t, dir, "go.sum", `github.com/nucleuskit/cap v0.1.0-alpha.2 h1:UnBp5ezoi+UrgT92DwpTdQynrEnUNnsf3rQKB0pNfPw= +github.com/nucleuskit/cap v0.1.0-alpha.2/go.mod h1:DLSQmS/6irYQfpWGJjce9+STvqG33yZMCxkwvdLf7XM= +github.com/nucleuskit/core v0.1.0-alpha.2 h1:CT4RJvCYtVNo0+Gqyf5zx4T90dBiXq4JVhQxEKBXyJ8= +github.com/nucleuskit/core v0.1.0-alpha.2/go.mod h1:fwIlIS28wLh/VQ/jhR4TgrZcrN1nOgrAxSYYYWRdEYk= +`) writeFile(t, dir, "demo.go", "package demo\n") writeFile(t, dir, "internal/app/routes.go", `package app @@ -374,3 +379,8 @@ func runtimeHTTPReplace(t *testing.T) string { } return filepath.ToSlash(path) } + +func localRuntimeReplace(t *testing.T) string { + t.Helper() + return "replace github.com/nucleuskit/http => " + runtimeHTTPReplace(t) + "\n" +} diff --git a/docs/implementation-status.md b/docs/implementation-status.md new file mode 100644 index 0000000..2666853 --- /dev/null +++ b/docs/implementation-status.md @@ -0,0 +1,89 @@ +# Implementation Status + +This document records what the current checkout actually implements. It is meant +to keep the public positioning honest: Nucleus is an AI-first microservice +kernel, not a production-complete replacement for go-zero, Kratos, go-kit, or a +full middleware platform. + +## Status Key + +| Status | Meaning | +| --- | --- | +| Implemented | Code exists, has tests, and is expected to work in the current checkout. | +| Published alpha | Code is available through published alpha module tags without local `replace` directives. | +| Scaffold | The CLI generates service-owned code or metadata, but does not wire a real provider automatically. | +| Fake/static | Useful for local tests, examples, or metadata checks; not a real external provider integration. | +| Metadata-only | Produces inspection or readiness evidence without starting business handlers or provider SDKs. | + +## CLI Surface + +| Command | Current status | Notes | +| --- | --- | --- | +| `nucleus init` | Implemented | Generates service, worker, and library templates. The service template is covered by tests that run validation, strict lint, and `go test ./...`. | +| `nucleus validate` | Implemented | Validates `nucleus.yaml`, `api/openapi.yaml`, `api/errors.yaml`, and lightweight proto facts. | +| `nucleus gen` | Implemented | Generates contract metadata, HTTP route binders, gRPC metadata, error metadata, docs, TypeScript schema exports, and minimal clients. | +| `nucleus lint` | Implemented | Checks architecture boundaries, route registration, capability graph, generated freshness, schema versions, and selected legacy imports. | +| `nucleus verify` | Implemented | Runs validate, strict lint, generated freshness, `go mod tidy`, import, build, and tests as evidence steps. | +| `nucleus describe` | Implemented | Emits manifest, contract, capability, module, edit-surface, freshness, and verification facts. | +| `nucleus plan` | Implemented | Produces task-oriented edit surfaces, commands, and risk notes. Natural-language classification is heuristic. | +| `nucleus apply` | Implemented | Applies plan file edits only after edit-surface, path traversal, and symlink checks. It deliberately does not execute shell commands. | +| `nucleus repair` | Implemented | Supports bounded repair for generated freshness and single explicit patch candidates with expected hashes. It is not a general code-repair engine. | +| `nucleus scenario` | Implemented | Builds OpenAPI/error-derived scenario suggestions and can run explicit HTTP scenario checks when a base URL or handler is provided. | +| `nucleus serve` | Metadata-only | Serves `/healthz`, `/readyz`, and `/.well-known/nucleus.json` metadata. It does not start generated business handlers. | +| `nucleus report` | Metadata-only | Summarizes local AI task quality and platform-readiness metadata without network calls. | +| `nucleus migrate` | Metadata-only | Produces migration checklists and readiness checks. It does not rewrite services. | +| `nucleus capability add` | Scaffold | Updates manifest metadata and generates service-owned component/app/docs scaffolds. Most providers still need explicit bridge wiring by the service. | + +## Contract and Manifest Layer + +| Area | Current status | Notes | +| --- | --- | --- | +| Manifest parsing | Implemented | Uses structured YAML parsing and validates required service metadata, capability names, dependencies, and AI edit surfaces. | +| OpenAPI inspection | Implemented | Loads route metadata, parameters, request-body facts, examples, and validation hints from `api/openapi.yaml`. It is a lightweight metadata parser, not a complete OpenAPI toolchain. | +| Proto inspection | Implemented | Extracts package, service, method, streaming, and `google.api.http` facts with a lightweight parser. It is not a replacement for `protoc`. | +| Error catalog | Implemented | Validates stable error codes, messages, and HTTP status mappings from `api/errors.yaml`. | +| Generated freshness | Implemented | Compares contract source hashes with generated target markers declared in `ai.generated`. | + +## Runtime Modules + +| Module | Current status | Notes | +| --- | --- | --- | +| `github.com/nucleuskit/http` | Published alpha | HTTP server, route registration, response envelopes, middleware, clients, CORS, SSE, static assets, and well-known metadata are implemented and tested. | +| `github.com/nucleuskit/grpc` | Published alpha | gRPC server/client wrappers, discovery resolver support, health/reflection options, and interceptor chains are implemented and tested. | +| `github.com/nucleuskit/worker` | Published alpha | Cron, interval, batch, consumer, stream, map-reduce, timing-wheel, hooks, and manager primitives are implemented and tested. | + +The runtime modules use canonical imports such as `github.com/nucleuskit/cap` +and `github.com/nucleuskit/core`, and the current alpha tags are verified +without local replacements. + +## Capabilities and Bridges + +| Area | Current status | Notes | +| --- | --- | --- | +| `github.com/nucleuskit/cap` | Implemented | Small capability interfaces, options, no-op implementations, and tests exist for auth, config, discovery, health, HTTP client, KV, lock, log, metric, Mongo, MQ, profiler, Redis, Sentinel, SQL, store, trace, and transport. | +| In-memory/test bridges | Fake/static | `memory`, `memorylock`, `redis`, `kv`, and several health/config helpers are useful for tests and local examples. They should not be presented as external managed services. | +| Real provider bridges | Implemented | `goredis`, `sarama`, `sql`, `gorm`, `zap`, `otel`, `prometheus`, `redislock`, and `nacosofficial` contain real provider-facing adapter code and tests. | +| Static provider bridges | Fake/static | `nacos` provides local/static config and discovery behavior. It is not the official Nacos SDK integration. | +| Provider scaffolds | Scaffold | `capability add` records provider intent and generates service-owned compile-safe code. Except for the focused PostgreSQL scaffold, it does not automatically import or wire provider SDKs. | + +## Examples + +The checked-in `examples/service`, `examples/worker`, and `examples/library` +directories describe templates rather than hosting full generated services. To +inspect a runnable service today, generate one with: + +```bash +nucleus init --template service --name demo-api --module example.com/demo-api --dir ./demo-api +cd ./demo-api +nucleus validate --dir . +nucleus lint --dir . --strict +nucleus verify --dir . --json +go test ./... +``` + +## Adoption Guidance + +Use the current checkout as an AI-safe contract, manifest, generation, and +evidence loop. Treat it as a production framework replacement only after more +real services have validated the runtime modules, bridge modules, examples, and +upgrade path under production-like constraints. diff --git a/examples/service/README.md b/examples/service/README.md index 66f10e3..a05359f 100644 --- a/examples/service/README.md +++ b/examples/service/README.md @@ -1,6 +1,9 @@ # Nucleus Service Template -Generated by: +This directory documents the generated service template. It is not itself a +checked-in runnable generated service. + +Generate a runnable service with: ```bash nucleus init --template service --name demo-api --module example.com/demo-api --dir ./demo-api @@ -16,4 +19,14 @@ The generated service includes: - `configs/config.example.yaml`, `docs/`, `deploy/`, and `test/integration/` scaffolding. - `AGENTS.md` with business-service edit rules and top-level directory registration. -Run `nucleus gen --dir .`, `nucleus lint --dir . --strict`, `nucleus verify --dir . --json`, and `go test ./...` after contract or implementation changes. +From the generated service directory, run: + +```bash +nucleus validate --dir . +nucleus lint --dir . --strict +nucleus verify --dir . --json +go test ./... +``` + +See [Implementation Status](../../docs/implementation-status.md) for the current +module and adapter status. diff --git a/go.mod b/go.mod index c310646..d97d928 100644 --- a/go.mod +++ b/go.mod @@ -3,14 +3,12 @@ module github.com/nucleuskit/nucleus go 1.26.3 require ( - github.com/nucleuskit/contract v0.1.0-alpha.2 + github.com/nucleuskit/contract v0.1.0-alpha.3 github.com/spf13/cobra v1.10.2 + go.yaml.in/yaml/v3 v3.0.4 ) require ( github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/spf13/pflag v1.0.10 // indirect - go.yaml.in/yaml/v3 v3.0.4 // indirect ) - -replace github.com/nucleuskit/contract => ./contract diff --git a/go.sum b/go.sum index 643e897..9a0b6e3 100644 --- a/go.sum +++ b/go.sum @@ -1,6 +1,8 @@ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/nucleuskit/contract v0.1.0-alpha.3 h1:RVa63tU3SZGrmVtX8vYP6RQHRLH4p28oLQKv1/kNI04= +github.com/nucleuskit/contract v0.1.0-alpha.3/go.mod h1:AVLCb1uBSCvd2CLoNvwUqsYN66sF6LWuKkLTeM4WjTk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= diff --git a/runtime/grpc b/runtime/grpc index 01e00d1..b824fcd 160000 --- a/runtime/grpc +++ b/runtime/grpc @@ -1 +1 @@ -Subproject commit 01e00d1fb8ee0c4405afc032bc60532a43e80641 +Subproject commit b824fcd86357688b9653c29a9b5f0c570325d860 diff --git a/runtime/http b/runtime/http index fe35dc3..c8f1e59 160000 --- a/runtime/http +++ b/runtime/http @@ -1 +1 @@ -Subproject commit fe35dc3c0bfc426d47dcaec5bcf0cb8d6d9f6377 +Subproject commit c8f1e5922b299b21f2261666a1921f7a8c1576c3 diff --git a/runtime/worker b/runtime/worker index 4093ccf..d85a5d2 160000 --- a/runtime/worker +++ b/runtime/worker @@ -1 +1 @@ -Subproject commit 4093ccf0cb820e5c89f9db5f30b4151c67547e6d +Subproject commit d85a5d2c816c5a34a8f10888ae133320e92c8750