Dev/main

.gitattributes

@@ -0,0 +1,15 @@
+# Normalize line endings to LF.
+* text eol=lf
+
+# Ensure that line endings for DOS batch files are not modified.
+*.bat -text
+
+# Ensure the following are treated as binary.
+*.gif   binary
+*.jar   binary
+*.jpeg  binary
+*.jpg   binary
+*.png   binary
+*.vsd   binary
+*.class   binary
+*.clazz   binary

.github/actions/await-http-resource/action.yml

@@ -0,0 +1,20 @@
+name: Await HTTP Resource
+description: 'Waits for an HTTP resource to be available (a HEAD request succeeds)'
+inputs:
+  url:
+    description: 'URL of the resource to await'
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Await HTTP resource
+      shell: bash
+      run: |
+        url=${{ inputs.url }}
+        echo "Waiting for $url"
+        until curl --fail --head --silent ${{ inputs.url }} > /dev/null
+        do
+          echo "."
+          sleep 60
+        done
+        echo "$url is available"

.github/actions/building/action.yml

@@ -0,0 +1,101 @@
+name: 'Build'
+description: 'Builds the project, optionally publishing it to a local deployment repository'
+inputs:
+  java-distribution:
+    description: 'Java distribution to use'
+    required: false
+    default: 'liberica'
+  java-early-access:
+    description: 'Whether the Java version is in early access'
+    required: false
+    default: 'false'
+  java-toolchain:
+    description: 'Whether a Java toolchain should be used'
+    required: false
+    default: 'false'
+  java-version:
+    description: 'Java version to compile and test with'
+    required: false
+    default: '24'
+  publish:
+    description: 'Whether to publish artifacts ready for deployment to Artifactory'
+    required: false
+    default: 'false'
+  token-password:
+    description: 'Password for authentication with central.sonatype.com'
+    required: false
+  token-username:
+    description: 'Username for authentication with central.sonatype.com'
+    required: false
+  signing-keyId:
+    description: 'signing keyId'
+    required: false
+  signing-password:
+    description: 'signing password'
+    required: false
+  gpg-passphrase:
+    description: 'Environment variable name for the GPG private key passphrase. Default is $GPG_PASSPHRASE.'
+    required: false
+  gpg-private-key:
+    description: 'GPG private key to import. Default is empty string.'
+    required: false
+  server-id:
+    description: 'ID of the distributionManagement repository in the pom.xml file. Default is `github`'
+    required: false
+    default: 'github'
+  server-username:
+    description: 'Environment variable name for the username for authentication to the Apache Maven repository. Default is $GITHUB_ACTOR'
+    required: false
+    default: 'GITHUB_ACTOR'
+  server-password:
+    description: 'Environment variable name for password or token for authentication to the Apache Maven repository. Default is $GITHUB_TOKEN'
+    required: false
+    default: 'GITHUB_TOKEN'
+outputs:
+  build-scan-url:
+    description: 'URL, if any, of the build scan produced by the build'
+    value: ${{ (inputs.publish == 'true' && steps.publish.outputs.build-scan-url) || steps.build.outputs.build-scan-url }}
+  version:
+    description: 'Version that was built'
+    value: ${{ steps.read-version.outputs.version }}
+runs:
+  using: composite
+  steps:
+    - name: Set Up Java
+      uses: actions/setup-java@v4
+      with:
+        distribution: ${{ inputs.java-early-access == 'true' && 'temurin' || (inputs.java-distribution || 'liberica') }}
+        java-version: |
+          ${{ inputs.java-early-access == 'true' && format('{0}-ea', inputs.java-version) || inputs.java-version }}
+          ${{ inputs.java-toolchain == 'true' && '17' || '' }}
+        gpg-passphrase: ${{ inputs.gpg-passphrase }}
+        gpg-private-key: ${{ inputs.gpg-private-key }}
+        server-id: ${{ inputs.server-id }}
+        server-username: ${{ inputs.server-username }}
+        server-password: ${{ inputs.server-password }}
+
+    - name: Print JDK Version
+      shell: bash
+      run: java -version
+
+    - name: Set Up Gradle
+      uses: gradle/actions/setup-gradle@v4
+
+    - name: Build
+      id: build
+      if: ${{ inputs.publish == 'false' }}
+      shell: bash
+      run: ./gradlew -DCI=true --no-daemon --no-parallel check --scan
+
+    - name: Publish
+      id: publish
+      if: ${{ inputs.publish == 'true' }}
+      shell: bash
+      run: ./gradlew --no-daemon --no-parallel publishMavenPublicationToSonatypeRepository closeAndReleaseStagingRepositories 
+            -PrepoUsername=${{ inputs.token-username }} -PrepoPassword=${{ inputs.token-password }} 
+            -Psigning.keyId=${{ inputs.signing-password }} -Psigning.password=${{ inputs.signing-password }}
+
+    - name: Read Version From gradle.properties
+      id: read-version
+      uses: ./.github/actions/read-version
+

.github/actions/read-version/action.yml

@@ -0,0 +1,24 @@
+name: read-version
+author: today
+description: Read project version
+
+outputs:
+  version:
+    description: 'Version of this project'
+    value: ${{ steps.read-version.outputs.version }}
+  snapshot:
+    description: 'Version is snapshot'
+    value: ${{ steps.read-version.outputs.snapshot }}
+runs:
+  using: composite
+  steps:
+    - name: Read Version From gradle.properties
+      id: read-version
+      shell: bash
+      run: |
+        version=$(sed -n 's/version=\(.*\)/\1/p' gradle.properties)
+        snapshot=$(echo $version | grep -q 'SNAPSHOT' && echo 'true' || echo 'false')
+        echo "Version is $version"
+        echo "snapshot = $snapshot"
+        echo "version=$version" >> $GITHUB_OUTPUT
+        echo "snapshot=$snapshot" >> $GITHUB_OUTPUT

.github/workflows/ci.yaml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+
+  pull_request:
+    branches:
+      - master
+      - 'dev/**'
+      - 'fix/**'
+      - 'feat/**'
+      - 'feature/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    if: github.repository_owner == 'today-tech'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        os: [ ubuntu-latest, macOS-latest ] #, windows-latest
+        java:
+          - version: 21
+            toolchain: true
+          - version: 24
+            toolchain: true
+      fail-fast: false
+      max-parallel: 4
+    name: JDK ${{ matrix.java.version }} on ${{ matrix.os }}
+
+    steps:
+      - name: Checkout project sources
+        uses: actions/checkout@v4.1.2
+
+      - name: Build
+        id: build
+        uses: ./.github/actions/building
+        with:
+          java-early-access: ${{ matrix.java.early-access || 'false' }}
+          java-distribution: ${{ matrix.java.distribution }}
+          java-toolchain: ${{ matrix.java.toolchain }}
+          java-version: ${{ matrix.java.version }}

.run/publishToMavenLocal.run.xml

@@ -0,0 +1,27 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="publishToMavenLocal" type="GradleRunConfiguration" factoryName="Gradle">
+    <ExternalSystemSettings>
+      <option name="executionName" />
+      <option name="externalProjectPath" value="$PROJECT_DIR$" />
+      <option name="externalSystemIdString" value="GRADLE" />
+      <option name="scriptParameters" value="-PskipDocs" />
+      <option name="taskDescriptions">
+        <list />
+      </option>
+      <option name="taskNames">
+        <list>
+          <option value="publishToMavenLocal" />
+        </list>
+      </option>
+      <option name="vmOptions" />
+    </ExternalSystemSettings>
+    <ExternalSystemDebugServerProcess>true</ExternalSystemDebugServerProcess>
+    <ExternalSystemReattachDebugProcess>true</ExternalSystemReattachDebugProcess>
+    <ExternalSystemDebugDisabled>false</ExternalSystemDebugDisabled>
+    <DebugAllEnabled>false</DebugAllEnabled>
+    <RunAsTest>false</RunAsTest>
+    <GradleProfilingDisabled>false</GradleProfilingDisabled>
+    <GradleCoverageDisabled>false</GradleCoverageDisabled>
+    <method v="2" />
+  </configuration>
+</component>

AGENTS.md

@@ -0,0 +1,29 @@
+# 仓库工作约定
+
+## 格式与文档（必须遵守）
+
+- 保留已有文件完整的版权头及 Apache 2.0 声明；重写文件不能丢失。新 Java 文件使用相邻文件的完整声明格式。
+- 保留已有 `@author` 和 `@since` 的原始内容，重构、改名不修改作者或创建时间。新增类型补齐作者和创建日期，遵循相邻文件格式。
+- 所有 Javadoc 使用多行 `/** ... */`，包括只有一句描述、一个 `@return` 或 `{@inheritDoc}` 的注释。禁止 `/** @return ... */`、`/** ... */` 这类单行 Javadoc。
+- 保持原有多行代码块：方法、构造器、`if`、`try`、`catch`、`finally`、多语句 lambda 不压成一行；方法和字段之间保留空行。
+- `.editorconfig`：UTF-8，Java/Groovy 使用 2 空格缩进和 LF，续行缩进为 8。保持原有 import 分组、排序和链式调用换行；不要顺便重排无关代码。
+- Javadoc 和源码注释使用英文；模块使用说明、设计文章使用中文，技术名称与代码保留英文。
+- Javadoc 说明真实生命周期：构造结果不等于执行完成，观察结果不应启动第二次调用；注明取消、线程与 buffer 所有权，不用过时的签名示例。
+
+## 构建与验证
+
+- 使用根目录 `./gradlew`。构建 toolchain 是 JDK 25，默认字节码 `--release 17`；README 的 JDK 17 标识不能当作构建 JDK 要求。配置见 `buildSrc/src/main/java/infra/cloud/JavaConventions.java`。
+- 模块测试：`./gradlew :today-service-provider:test --console=plain`；单类测试：`./gradlew :today-service-provider:test --tests infra.cloud.provider.ServiceInterceptorTests --console=plain`。
+- 跨结果/API/两端调用链的修改：`./gradlew :today-service-api:test :today-service-client:test :today-service-provider:test --console=plain`。
+- 文档检查：`./gradlew :today-service-provider:javadoc --console=plain`，另运行 `git diff --check`。Javadoc 配置了 `failOnError = false`，任务成功不代表没有文档问题；外部链接可能让生成耗时较长。
+- 测试只包含 `*Tests` / `*Test` 类，使用 JUnit Platform；默认 Netty leak detection 为 `paranoid`。沿用 Gradle 测试配置，不手动另配 JVM opens。
+- 仓库优先解析 `mavenLocal()`，snapshot/dynamic 依赖缓存时间为零。依赖已缓存时可加 `--offline`；它不会阻止 Javadoc 工具访问外部文档链接。
+- `infra.test.app.context.InfraTest` 的应用上下文测试需要模块测试 classpath 包含 `cn.taketoday:infra-app`；`infra-test` 单独不足。
+
+## 代码边界
+
+- 已有 `.codegraph/` 索引，定位符号及调用链优先使用 CodeGraph；配置和文档用直接读取。
+- `today-service-api` 放共享请求元数据和结果契约；client/provider 各有自己的拦截链与上下文。两端同名 `InterceptorChain` / `DefaultInterceptorChain` 位于不同包，避免误导入。
+- provider 调用接线在 `ServiceProviderAutoConfiguration`；`ServiceMethodResolver` 构建并缓存 `InvocableMethod`，方法预绑定 `ReturnValueHandler`。调用级参数、attributes、metadata 属于 `RemoteRequest`，不能放进共享方法或不可变链节点。
+- 跨进程 `Metadata` 与本地 `AttributeAccessor` 分开。服务端在释放入站 Payload 前解码元数据，保存独立快照，不留已释放 ByteBuf 的 slice；本地 attributes 不自动发送。
+- provider 边界与扩展方式见 `today-service-provider/README.md`。公开接口不暴露 Mono 并不意味着默认实现已移除 Reactor；不要把未实现的流式接入或依赖移除写成完成状态。