Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,14 @@ jobs:
with:
path: provider

# Loader 编译到契约;共享层不进 Loader 包(ADR-0036)。
# Loader 编译到契约;共享层不进 Loader 包(FX-0036)。
- name: 契约
uses: actions/checkout@v7
with:
repository: HosihikariFramework/PluginAbstractions
path: Plugin.Abstractions

# 打包器在核心仓;共享层清单由它统一给出(ADR-0036)。
# 打包器在核心仓;共享层清单由它统一给出(FX-0036)。
- name: 核心打包器
uses: actions/checkout@v7
with:
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ checkouts. `pack.ps1` calls the core packer and needs the same `PluginManager` c
- Cache keys cover source text, `#load` and local `#r` inputs, package-local DLLs, compiler version,
and runtime version. Keep the checksum check in sync.
- Operator-facing messages come from `src/Resources/LoaderStrings.resx` (neutral English) and
`LoaderStrings.zh.resx`; exception messages are English (ADR-0050).
`LoaderStrings.zh.resx`; exception messages are English (FX-0050).
- A failed load releases its ALC. After excluding abstract/interface types and implementations
without a public parameterless constructor, a package exposes exactly one `IPlugin` candidate.
- Public default branches are protected. Work on a branch, open a pull request, and squash merge.
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ loader loads that IL into a collectible ALC.

**In-process .NET.** The framework keeps the assembly loader, the C# loader and this F# loader
in-process; other languages go through the generic out-of-process loader
(`Hosihikari.PluginLoader.Rpc`, ADR-0031).
(`Hosihikari.PluginLoader.Rpc`, FX-0031).

## Templates

Expand Down Expand Up @@ -93,8 +93,8 @@ globs or unresolved paths are recompiled on every load into a unique `-run-` dir
comments or ordinary strings is not a directive and no longer forces recompilation.

The checksum guards against accidents (a swapped or half-written artifact, a compiler or runtime
change), not against a hostile plugin: plugins share this process and are trusted (ADR-0011), so one
could forge the cache as well. ADR-0029 records that boundary.
change), not against a hostile plugin: plugins share this process and are trusted (FX-0011), so one
could forge the cache as well. FX-0029 records that boundary.

## Running it

Expand Down Expand Up @@ -140,8 +140,8 @@ pwsh ./pack.ps1 -Version 1.0.0 -OutputRoot artifacts

It assembles the loader DLL, its private dependencies and `hosihikari.json` into
`plugins/hosihikari-fsharp/`; the packer generates the LeviLamina `manifest.json` envelope from it
(ADR-0058), and the shared layer is not copied. Pushing a `v*` tag attaches the zip
to the GitHub release (ADR-0044).
(FX-0058), and the shared layer is not copied. Pushing a `v*` tag attaches the zip
to the GitHub release (FX-0044).

The script invokes the core packager (`PluginManager/tools/Pack`), which owns the
shared-layer list. Check out the core repository alongside this one, or set
Expand Down
6 changes: 3 additions & 3 deletions README.zh_hans.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
这是进程内加载器:在插件开始运行前把源码编译为 IL,加载器把 IL 装进 collectible ALC。

**进程内只留 .NET。** 框架在进程内保留程序集型、C# 与 F# 三个加载器;其他语言走
通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,ADR-0031)。
通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,FX-0031)。

## 模板

Expand Down Expand Up @@ -84,7 +84,7 @@ TPA 里也从这里拿)、包根目录内的私有 DLL、这个加载器自己
注释与普通字符串里的 `#` 不是指令,不再触发重编。

校验和防的是**事故**(产物被换掉或写坏、编译器或运行时换了一版),不防**恶意**:插件与本框架同进程、
且完全受信(ADR-0011),它真要伪造缓存也做得到。这条边界记在 ADR-0029 里。
且完全受信(FX-0011),它真要伪造缓存也做得到。这条边界记在 FX-0029 里。

## 跑一遍

Expand Down Expand Up @@ -120,7 +120,7 @@ dotnet run --project host/Hosihikari.PluginLoader.FSharp.Host.csproj -c Release
pwsh ./pack.ps1 -Version 1.0.0 -OutputRoot artifacts
```

它把加载器 DLL、私有依赖与 `hosihikari.json` 装进 `plugins/hosihikari-fsharp/`,信封 `manifest.json` 由打包器生成(ADR-0058),共享层不随包走;打 `v*` 标签时 CI 把 zip 附到 release(ADR-0044)。
它把加载器 DLL、私有依赖与 `hosihikari.json` 装进 `plugins/hosihikari-fsharp/`,信封 `manifest.json` 由打包器生成(FX-0058),共享层不随包走;打 `v*` 标签时 CI 把 zip 附到 release(FX-0044)。

打包脚本调用插件管理器打包器(`PluginManager/tools/Pack`),共享层清单由插件管理器统一给出;需要并列检出插件管理器仓,或设置 `HOSIHIKARI_PLUGINMANAGER`。

Expand Down
16 changes: 8 additions & 8 deletions host/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
CultureInfo.DefaultThreadCurrentUICulture = CultureInfo.GetCultureInfo("zh-Hans");
CultureInfo.CurrentUICulture = CultureInfo.GetCultureInfo("zh-Hans");

// 载体中立检查(ADR-0015):普通 .NET 控制台驱动核心,不碰 BDS、Shim、任何载体。
// 载体中立检查(FX-0015):普通 .NET 控制台驱动核心,不碰 BDS、Shim、任何载体。
//
// 宿主**不直接注册** F# 加载器 —— 它把加载器当成一个插件包装进去,由那个包在 OnLoad
// 里把自己登记给框架(ADR-0002)。第二步才是 F# 的本体:装载时把 .fsx 编成程序集,进一个
// 里把自己登记给框架(FX-0002)。第二步才是 F# 的本体:装载时把 .fsx 编成程序集,进一个
// collectible ALC。
var stage = Path.Combine(Path.GetTempPath(), "hosihikari-fsharp-spike");
if (Directory.Exists(stage))
Expand All @@ -28,7 +28,7 @@
StageLoaderPackage();
var nativeStaged = StageScriptPackage();

// 运营方的覆盖放包外(ADR-0018)—— 脚本读到的应当是这一份。
// 运营方的覆盖放包外(FX-0018)—— 脚本读到的应当是这一份。
File.WriteAllText(Path.Combine(configRoot, "Hello.conf"), "greeting = \"overridden\"\n");

var collection = new ServiceCollection();
Expand All @@ -55,7 +55,7 @@
host.LoadAll();
Console.WriteLine($"已加载:{string.Join(", ", host.LoadedNames)}");

// 程序集这一侧发一条通道消息 —— 与 F# 脚本用的是同一个载荷类型(ADR-0026)。
// 程序集这一侧发一条通道消息 —— 与 F# 脚本用的是同一个载荷类型(FX-0026)。
host.Events.Publish(new Hosihikari.ChannelMessage("ping", "\"from-host\""));

var dataDirectory = Path.Combine(dataRoot, "Hello");
Expand All @@ -81,15 +81,15 @@

checks.Add(("启用钩子到达脚本", Read("enabled.txt") == "enabled", Read("enabled.txt")));

// 编出来的 F# 插件拿得到完整契约 —— 包括按类型做键的通道(ADR-0026)。
// 编出来的 F# 插件拿得到完整契约 —— 包括按类型做键的通道(FX-0026)。
checks.Add(("程序集发的通道消息被 F# 插件收到", Read("ping.txt") == "ping:\"from-host\"", Read("ping.txt")));

// 包内自带的第三方依赖:编译期看得见、运行期从包里解析。
var expectedHash = Convert.ToHexStringLower(System.IO.Hashing.XxHash128.Hash(new byte[] { 1, 2, 3 }));
checks.Add(("包内自带的第三方依赖可用", Read("hash.txt") == expectedHash, Read("hash.txt")));
checks.Add(("宿主未引用的包内私有依赖可用", Read("private.txt") == "private-dependency", Read("private.txt")));

// 本机库按 RID 目录优先解析(ADR-0034);包根那份是 1,RID 那份是 42。
// 本机库按 RID 目录优先解析(FX-0034);包根那份是 1,RID 那份是 42。
checks.Add((
"本机库按 RID 目录解析",
!nativeStaged || Read("native.txt") == "42",
Expand Down Expand Up @@ -784,7 +784,7 @@ void StageLoaderPackage()
}
""");

// 整个构建输出随包走,只把共享层剔掉(ADR-0004)。
// 整个构建输出随包走,只把共享层剔掉(FX-0004)。
var output = Path.Combine(RepoRoot(), "src", "bin", ConfigurationName(), "net10.0");
foreach (var file in Directory.EnumerateFiles(output, "*.dll"))
{
Expand Down Expand Up @@ -822,7 +822,7 @@ bool StageScriptPackage()
}
""");

// 作者给的默认值,随包更新(ADR-0018)。
// 作者给的默认值,随包更新(FX-0018)。
File.WriteAllText(Path.Combine(package, "Hello.conf"), "greeting = \"package\"\n");

// 包里自带的第三方依赖:不是框架的一部分,编译期与运行期都得从包里拿。
Expand Down
4 changes: 2 additions & 2 deletions pack.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

The package is a plugin package itself: loader DLL, private dependencies and
the author manifest. Shared-layer assemblies are excluded by the core packager
from its canonical list (ADR-0019 / 0026 / 0036). The LeviLamina envelope
(`manifest.json`) is generated by the packer, never written here (ADR-0058).
from its canonical list (FX-0019 / 0026 / 0036). The LeviLamina envelope
(`manifest.json`) is generated by the packer, never written here (FX-0058).

Requires a sibling PluginManager checkout, or HOSIHIKARI_PLUGINMANAGER.

Expand Down
18 changes: 9 additions & 9 deletions src/FSharpPluginLoader.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@
namespace Hosihikari.PluginLoader.FSharp;

/// <summary>
/// F# 型插件的加载器(ADR-0002 的扩展点)。
/// F# 型插件的加载器(FX-0002 的扩展点)。
///
/// F# 直接跑在 CLR 上。这个加载器做的事是**装载时编译**:
/// 把清单 <c>entry</c> 指向的 <c>.fsx</c> 编成一个程序集,再交给一个 collectible ALC。
///
/// 编译产物按**内容寻址**缓存(ADR-0029):目录名是脚本内容、#load/#r 依赖、编译器与运行时版本的哈希,
/// 编译产物按**内容寻址**缓存(FX-0029):目录名是脚本内容、#load/#r 依赖、编译器与运行时版本的哈希,
/// 所以任何一份输入一改就换目录,旧代码不可能被跑到;产物旁另存一份校验和,加载前对一遍。
///
/// 入口靠约定:编出来的程序集里那个实现 <see cref="IPlugin"/>、有无参构造的类型(ADR-0008)。
/// 入口靠约定:编出来的程序集里那个实现 <see cref="IPlugin"/>、有无参构造的类型(FX-0008)。
/// </summary>
public sealed class FSharpPluginLoader : IPluginLoader
{
Expand Down Expand Up @@ -158,7 +158,7 @@
{
context.Logger.LogError(
"{Message}",
LoaderText.Get("EntryCreateFailed", candidates[0].FullName));

Check warning on line 161 in src/FSharpPluginLoader.cs

View workflow job for this annotation

GitHub Actions / assertions (windows-latest)

Possible null reference argument for parameter 'arguments' in 'string LoaderText.Get(string key, params object[] arguments)'.

Check warning on line 161 in src/FSharpPluginLoader.cs

View workflow job for this annotation

GitHub Actions / assertions (ubuntu-latest)

Possible null reference argument for parameter 'arguments' in 'string LoaderText.Get(string key, params object[] arguments)'.
loadContext.Unload();
return null;
}
Expand Down Expand Up @@ -847,15 +847,15 @@
return true;
}

/// <summary>插件目录里自带的依赖;框架已经有的那些不算(共享层,ADR-0004)。</summary>
/// <summary>插件目录里自带的依赖;框架已经有的那些不算(共享层,FX-0004)。</summary>
private static IReadOnlyList<string> LocalAssemblies(string packageDirectory) =>
Directory.EnumerateFiles(packageDirectory, "*.dll")
.Where(IsManagedAssembly)
.Where(path => !IsFrameworkAssembly(Path.GetFileNameWithoutExtension(path)))
.OrderBy(path => path, StringComparer.Ordinal)
.ToArray();

/// <summary>包根可以有本机库(ADR-0034);它们不能当编译器的元数据引用。</summary>
/// <summary>包根可以有本机库(FX-0034);它们不能当编译器的元数据引用。</summary>
private static bool IsManagedAssembly(string path)
{
try
Expand All @@ -869,7 +869,7 @@
}
}

// 共享层按契约的清单判(ADR-0019 / 0026),不看宿主恰好加载过什么:
// 共享层按契约的清单判(FX-0019 / 0026),不看宿主恰好加载过什么:
// 否则插件自带的同名库会被静默顶掉,还不进缓存键。
private static bool IsFrameworkAssembly(string name) =>
PluginContractInfo.BaseSharedAssemblyFileNames
Expand Down Expand Up @@ -951,7 +951,7 @@
}
catch (Exception ex)
{
// 编译期出错只让这一个插件倒下(ADR-0009)。
// 编译期出错只让这一个插件倒下(FX-0009)。
context.Logger.LogError(ex, "{Message}", LoaderText.Get("CompileFailed", scriptPath));
return false;
}
Expand Down Expand Up @@ -1219,7 +1219,7 @@

protected override IntPtr LoadUnmanagedDll(string unmanagedDllName)
{
// 本机库随进程存活;这里只负责按 RID → 包根的顺序找到它(ADR-0034)。
// 本机库随进程存活;这里只负责按 RID → 包根的顺序找到它(FX-0034)。
var path = FindNativeLibrary(_packageDirectory, unmanagedDllName);
return path is null ? IntPtr.Zero : LoadUnmanagedDllFromPath(path);
}
Expand Down Expand Up @@ -1288,7 +1288,7 @@

public override bool IsUnloaded => _weakContext is { IsAlive: false };

/// <summary>编出来的程序集就是搬运单元(ADR-0010):放下它,回收照常验证(ADR-0023)。</summary>
/// <summary>编出来的程序集就是搬运单元(FX-0010):放下它,回收照常验证(FX-0023)。</summary>
public override void Unload()
{
if (_loadContext is null)
Expand Down
6 changes: 3 additions & 3 deletions src/LoaderBootstrap.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,17 @@
namespace Hosihikari.PluginLoader.FSharp;

/// <summary>
/// 加载器本身就是一个插件包(ADR-0002):它在装载时把自己登记给框架,此后要路由给
/// 加载器本身就是一个插件包(FX-0002):它在装载时把自己登记给框架,此后要路由给
/// F# 的包才会被它接管。
///
/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(ADR-0006),依赖图会先排它。
/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(FX-0006),依赖图会先排它。
/// 登记之后不能撤销,所以本包装上就别指望能卸掉:它造出来的实例的类型住在它的装载上下文里。
/// </summary>
public sealed class LoaderBootstrap : IPlugin
{
public ValueTask OnLoad(IPluginContext context, CancellationToken cancellationToken)
{
// 加载器包按清单的 kind 拿到 ILoaderContext(ADR-0059);拿不到说明清单漏写了 kind。
// 加载器包按清单的 kind 拿到 ILoaderContext(FX-0059);拿不到说明清单漏写了 kind。
if (context is not ILoaderContext loaderContext)
{
throw new InvalidOperationException(
Expand Down
2 changes: 1 addition & 1 deletion src/ScriptHost.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ namespace Hosihikari.PluginLoader.FSharp;
/// <summary>
/// 脚本看得见的那一个全局对象 <c>hosihikari</c>。
///
/// 它是**能力面**本身:ADR-0001 把框架的能力面卡在宿主服务上,所以这里只有日志、配置、
/// 它是**能力面**本身:FX-0001 把框架的能力面卡在宿主服务上,所以这里只有日志、配置、
/// 数据目录与调度。事件总线与服务注册表都按类型做键,而脚本这边没有共享类型 ——
/// 那两样暂时够不着,等有了共享的载荷词汇再说。
/// </summary>
Expand Down
6 changes: 3 additions & 3 deletions src/ScriptPlugin.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ namespace Hosihikari.PluginLoader.FSharp;

/// <summary>
/// 脚本插件在契约这边的样子。脚本本体在装载时就跑完了,这里只持有它在运行期登记的
/// 那几个钩子 —— 启停顺序仍由框架驱动(ADR-0013),与程序集型插件一致。
/// 那几个钩子 —— 启停顺序仍由框架驱动(FX-0013),与程序集型插件一致。
/// </summary>
internal sealed class ScriptPlugin(IPluginContext context) : IPlugin
{
Expand All @@ -19,7 +19,7 @@ internal sealed class ScriptPlugin(IPluginContext context) : IPlugin

public void OnUnloadHook(Action callback) => _unload.Add(callback);

/// <summary>脚本从头跑到尾,装载阶段没有额外的钩子要调(ADR-0008)。</summary>
/// <summary>脚本从头跑到尾,装载阶段没有额外的钩子要调(FX-0008)。</summary>
public ValueTask OnLoad(IPluginContext context, CancellationToken cancellationToken) => ValueTask.CompletedTask;

public ValueTask<PluginHookResult> OnEnable(CancellationToken cancellationToken)
Expand All @@ -40,7 +40,7 @@ public ValueTask OnUnload(CancellationToken cancellationToken)
return ValueTask.CompletedTask;
}

/// <summary>一个钩子抛出不影响其余的,也不越过契约边界(ADR-0009 / 0014)。</summary>
/// <summary>一个钩子抛出不影响其余的,也不越过契约边界(FX-0009 / 0014)。</summary>
private void Invoke(List<Action> callbacks, string hook)
{
foreach (var callback in callbacks)
Expand Down