Skip to content

Commit 9b57f47

Browse files
authored
Merge pull request #176 from Astn/aus-1013-freeze
AUS-1013: package-link check, API surface dumps and an upgrading note
2 parents 950bf8f + f0a7f13 commit 9b57f47

7 files changed

Lines changed: 1578 additions & 0 deletions

File tree

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<Project Sdk="Microsoft.NET.Sdk.Web">
2+
<PropertyGroup>
3+
<OutputType>Exe</OutputType>
4+
<TargetFramework>net10.0</TargetFramework>
5+
<Nullable>disable</Nullable>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<JsonRpcVersion Condition="'$(JsonRpcVersion)' == ''">2.0.0-preview.3</JsonRpcVersion>
8+
<NoWarn>$(NoWarn);CS0618;JSONRPC0001;JSONRPC0002;JSONRPC0003</NoWarn>
9+
</PropertyGroup>
10+
<ItemGroup>
11+
<PackageReference Include="AustinHarris.JsonRpc" Version="$(JsonRpcVersion)" />
12+
<PackageReference Include="AustinHarris.JsonRpc.AspNetCore" Version="$(JsonRpcVersion)" />
13+
<PackageReference Include="AustinHarris.JsonRpc.SystemTextJson" Version="$(JsonRpcVersion)" />
14+
<PackageReference Include="AustinHarris.JsonRpc.Newtonsoft" Version="$(JsonRpcVersion)" />
15+
</ItemGroup>
16+
</Project>
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
using System.Reflection;
2+
using System.Text;
3+
4+
// Dumps the public API surface of the four assemblies as sorted text, one member per line, so two versions diff.
5+
var names = new[] { "AustinHarris.JsonRpc", "AustinHarris.JsonRpc.AspNetCore", "AustinHarris.JsonRpc.SystemTextJson", "AustinHarris.JsonRpc.Newtonsoft" };
6+
var sb = new StringBuilder();
7+
foreach (var name in names)
8+
{
9+
var asm = Assembly.Load(name);
10+
var an = asm.GetName();
11+
sb.AppendLine($"## {an.Name} {an.Version} PublicKeyToken={Convert.ToHexString(an.GetPublicKeyToken() ?? Array.Empty<byte>()).ToLowerInvariant()}");
12+
var informational = asm.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion ?? "";
13+
sb.AppendLine($" informational={informational.Split('+')[0]}");
14+
foreach (var t in asm.GetExportedTypes().OrderBy(t => t.FullName, StringComparer.Ordinal))
15+
{
16+
if (t.IsNested && !(t.IsNestedPublic || t.IsNestedFamily || t.IsNestedFamORAssem)) continue;
17+
string kind = t.IsInterface ? "interface" : t.IsEnum ? "enum" : t.IsValueType ? "struct" : t.IsSubclassOf(typeof(Delegate)) ? "delegate" : t.IsAbstract && t.IsSealed ? "static class" : t.IsAbstract ? "abstract class" : t.IsSealed ? "sealed class" : "class";
18+
var bases = new List<string>();
19+
if (t.BaseType != null && t.BaseType != typeof(object) && t.BaseType != typeof(ValueType) && t.BaseType != typeof(Enum) && t.BaseType != typeof(MulticastDelegate)) bases.Add(t.BaseType.FullName ?? t.BaseType.Name);
20+
bases.AddRange(t.GetInterfaces().Where(i => i.IsPublic || i.IsNestedPublic).Select(i => i.FullName ?? i.Name).OrderBy(x => x, StringComparer.Ordinal));
21+
sb.AppendLine($"{kind} {t.FullName}{(bases.Count > 0 ? " : " + string.Join(", ", bases) : "")}");
22+
if (t.IsEnum)
23+
{
24+
foreach (var v in Enum.GetNames(t)) sb.AppendLine($" {v} = {Convert.ToInt64(Enum.Parse(t, v))}");
25+
continue;
26+
}
27+
var flags = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly;
28+
var lines = new List<string>();
29+
foreach (var m in t.GetMembers(flags))
30+
{
31+
if (!Visible(m)) continue;
32+
if (m is MethodInfo mi && mi.IsSpecialName) continue; // property/event accessors, operators listed via the property
33+
string prefix = m switch { ConstructorInfo => "ctor", MethodInfo => "method", PropertyInfo => "property", FieldInfo => "field", EventInfo => "event", Type => "nested", _ => m.MemberType.ToString() };
34+
string text = m switch
35+
{
36+
PropertyInfo p => $"{TypeName(p.PropertyType)} {p.Name}{Indexer(p)} {{ {(p.GetMethod != null && Visible(p.GetMethod) ? "get; " : "")}{(p.SetMethod != null && Visible(p.SetMethod) ? "set; " : "")}}}",
37+
FieldInfo f => $"{(f.IsStatic ? "static " : "")}{(f.IsInitOnly ? "readonly " : "")}{(f.IsLiteral ? "const " : "")}{TypeName(f.FieldType)} {f.Name}",
38+
EventInfo e => $"{TypeName(e.EventHandlerType)} {e.Name}",
39+
ConstructorInfo c => $"{(c.IsStatic ? "static " : "")}{t.Name}({Params(c.GetParameters())})",
40+
MethodInfo mm => $"{(mm.IsStatic ? "static " : "")}{(mm.IsAbstract ? "abstract " : mm.IsVirtual && !mm.IsFinal ? "virtual " : "")}{TypeName(mm.ReturnType)} {mm.Name}{Generic(mm)}({Params(mm.GetParameters())})",
41+
Type nt => nt.Name,
42+
_ => m.Name,
43+
};
44+
string access = Access(m);
45+
lines.Add($" {access} {prefix} {text}");
46+
}
47+
foreach (var l in lines.OrderBy(x => x, StringComparer.Ordinal)) sb.AppendLine(l);
48+
}
49+
}
50+
var outPath = args.Length > 0 ? args[0] : "api.txt";
51+
File.WriteAllText(outPath, sb.ToString());
52+
Console.WriteLine("written " + outPath);
53+
54+
static bool Visible(MemberInfo m) => m switch
55+
{
56+
MethodBase mb => mb.IsPublic || mb.IsFamily || mb.IsFamilyOrAssembly,
57+
FieldInfo f => f.IsPublic || f.IsFamily || f.IsFamilyOrAssembly,
58+
PropertyInfo p => (p.GetMethod != null && Visible(p.GetMethod)) || (p.SetMethod != null && Visible(p.SetMethod)),
59+
EventInfo e => e.AddMethod != null && Visible(e.AddMethod),
60+
Type t => t.IsNestedPublic || t.IsNestedFamily || t.IsNestedFamORAssem,
61+
_ => false,
62+
};
63+
static string Access(MemberInfo m) => m switch
64+
{
65+
MethodBase mb => mb.IsPublic ? "public" : "protected",
66+
FieldInfo f => f.IsPublic ? "public" : "protected",
67+
PropertyInfo p => (p.GetMethod?.IsPublic ?? false) || (p.SetMethod?.IsPublic ?? false) ? "public" : "protected",
68+
EventInfo e => e.AddMethod.IsPublic ? "public" : "protected",
69+
Type t => t.IsNestedPublic ? "public" : "protected",
70+
_ => "?",
71+
};
72+
static string TypeName(Type t)
73+
{
74+
if (t.IsByRef) return "ref " + TypeName(t.GetElementType());
75+
if (t.IsArray) return TypeName(t.GetElementType()) + "[]";
76+
if (t.IsGenericParameter) return t.Name;
77+
if (t.IsGenericType)
78+
{
79+
var def = t.GetGenericTypeDefinition();
80+
string baseName = (def.FullName ?? def.Name).Split('`')[0];
81+
return baseName + "<" + string.Join(", ", t.GetGenericArguments().Select(TypeName)) + ">";
82+
}
83+
return t.FullName ?? t.Name;
84+
}
85+
static string Params(ParameterInfo[] ps) => string.Join(", ", ps.Select(p => $"{(p.IsOut ? "out " : p.ParameterType.IsByRef && p.IsIn ? "in " : "")}{TypeName(p.ParameterType)} {p.Name}{(p.HasDefaultValue ? " = " + (p.DefaultValue ?? "null") : "")}"));
86+
static string Generic(MethodInfo m) => m.IsGenericMethodDefinition ? "<" + string.Join(", ", m.GetGenericArguments().Select(a => a.Name)) + ">" : "";
87+
static string Indexer(PropertyInfo p) { var ps = p.GetIndexParameters(); return ps.Length == 0 ? "" : "[" + Params(ps) + "]"; }
Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
#!/usr/bin/env python3
2+
"""Checks that a published version of the four packages points at pages that exist.
3+
4+
For each of AustinHarris.JsonRpc, .AspNetCore, .SystemTextJson and .Newtonsoft at the given version, the script
5+
downloads the .nupkg from nuget.org, reads projectUrl, the repository url, releaseNotes and the package README out
6+
of the .nuspec, and requests every absolute http(s) URL found in them, expecting a 2xx. It then builds a scratch
7+
console project against the core package, prints the ObsoleteAttribute on Handler.RegisterFuction,
8+
Handler.UnRegisterFunction and Config.SetBeforeProcessHandler as the published assembly carries it, formats each
9+
UrlFormat with its DiagnosticId, requests the page and asserts the anchor id is in the HTML.
10+
11+
Usage: python3 .github/scripts/check_package_links.py 2.0.0-preview.3 [--keep] (exit 1 on any failure)
12+
13+
The check runs against nuget.org, so it is a release step (after the publish workflow has run and the flat
14+
container lists the version, which lags the push by a few minutes), not a pull-request gate.
15+
"""
16+
import io
17+
import os
18+
import re
19+
import shutil
20+
import subprocess
21+
import sys
22+
import tempfile
23+
import urllib.error
24+
import urllib.request
25+
import xml.etree.ElementTree as ET
26+
import zipfile
27+
28+
PACKAGES = ["AustinHarris.JsonRpc", "AustinHarris.JsonRpc.AspNetCore", "AustinHarris.JsonRpc.SystemTextJson",
29+
"AustinHarris.JsonRpc.Newtonsoft"]
30+
FLAT = "https://api.nuget.org/v3-flatcontainer/{id}/{version}/{id}.{version}.nupkg"
31+
OBSOLETE = { # member -> expected diagnostic id
32+
"Handler.RegisterFuction": "JSONRPC0002",
33+
"Handler.UnRegisterFunction": "JSONRPC0003",
34+
"Config.SetBeforeProcessHandler": "JSONRPC0001",
35+
}
36+
URL = re.compile(r"https?://[^\s<>()\"'`\]]+")
37+
# Sample addresses in the READMEs (a host the reader runs) are not links to check.
38+
LOCAL = re.compile(r"^https?://(localhost|127\.0\.0\.1|\[::1\]|[^/]+\.(test|example|localhost)|example\.(com|org|net))(:\d+)?(/|$)", re.I)
39+
HEADERS = {"User-Agent": "JSON-RPC.NET package-link check (+https://github.com/Astn/JSON-RPC.NET)"}
40+
41+
PROGRAM = r"""
42+
using System;
43+
using System.Linq;
44+
using System.Reflection;
45+
using AustinHarris.JsonRpc;
46+
47+
static class Program
48+
{
49+
static void Main()
50+
{
51+
const BindingFlags All = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance;
52+
foreach (var m in typeof(Handler).GetMethods(All).Where(m => m.Name == "RegisterFuction" || m.Name == "UnRegisterFunction")
53+
.Concat(typeof(Config).GetMethods(All).Where(m => m.Name == "SetBeforeProcessHandler")))
54+
foreach (var a in m.GetCustomAttributes<ObsoleteAttribute>())
55+
Console.WriteLine(m.DeclaringType.Name + "." + m.Name + "|" + a.DiagnosticId + "|" + a.UrlFormat + "|" + a.Message);
56+
Console.WriteLine("assembly|" + typeof(Handler).Assembly.GetName().FullName);
57+
}
58+
}
59+
"""
60+
61+
PROJECT = """<Project Sdk="Microsoft.NET.Sdk">
62+
<PropertyGroup>
63+
<OutputType>Exe</OutputType>
64+
<TargetFramework>net8.0</TargetFramework>
65+
<Nullable>disable</Nullable>
66+
</PropertyGroup>
67+
<ItemGroup>
68+
<PackageReference Include="AustinHarris.JsonRpc" Version="{version}" />
69+
</ItemGroup>
70+
</Project>
71+
"""
72+
73+
NUGET_CONFIG = """<?xml version="1.0" encoding="utf-8"?>
74+
<configuration>
75+
<packageSources>
76+
<clear />
77+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
78+
</packageSources>
79+
</configuration>
80+
"""
81+
82+
failures = []
83+
84+
85+
def fail(message):
86+
failures.append(message)
87+
print("FAIL " + message)
88+
89+
90+
def fetch(url, binary=False):
91+
req = urllib.request.Request(url, headers=HEADERS)
92+
with urllib.request.urlopen(req, timeout=60) as r:
93+
data = r.read()
94+
return (r.status, data if binary else data.decode("utf-8", "replace"))
95+
96+
97+
def status(url):
98+
try:
99+
return fetch(url)[0]
100+
except urllib.error.HTTPError as e:
101+
return e.code
102+
except Exception as e: # DNS, TLS, timeout
103+
return str(e)
104+
105+
106+
def text(node):
107+
return (node.text or "").strip() if node is not None else ""
108+
109+
110+
def strip_trailing(url):
111+
return url.rstrip(".,;:!?)")
112+
113+
114+
def check_package(package, version, workdir):
115+
print("== " + package + " " + version)
116+
url = FLAT.format(id=package.lower(), version=version.lower())
117+
try:
118+
code, data = fetch(url, binary=True)
119+
except urllib.error.HTTPError as e:
120+
fail("%s: nupkg download %s -> %s" % (package, url, e.code))
121+
return
122+
path = os.path.join(workdir, package + "." + version + ".nupkg")
123+
with open(path, "wb") as f:
124+
f.write(data)
125+
z = zipfile.ZipFile(io.BytesIO(data))
126+
spec_name = [n for n in z.namelist() if n.endswith(".nuspec")][0]
127+
root = ET.fromstring(z.read(spec_name))
128+
ns = {"n": root.tag[1:].split("}")[0]} if root.tag.startswith("{") else {}
129+
meta = root.find("n:metadata", ns) if ns else root.find("metadata")
130+
131+
def field(name):
132+
return text(meta.find("n:" + name, ns) if ns else meta.find(name))
133+
134+
spec_version = field("version")
135+
if spec_version != version:
136+
fail("%s: nuspec version %s, expected %s" % (package, spec_version, version))
137+
project_url = field("projectUrl")
138+
repo = meta.find("n:repository", ns) if ns else meta.find("repository")
139+
repo_url = repo.get("url") if repo is not None else ""
140+
notes = field("releaseNotes")
141+
readme_name = field("readme")
142+
if not project_url:
143+
fail(package + ": no projectUrl")
144+
if not repo_url:
145+
fail(package + ": no repository url")
146+
if not notes:
147+
fail(package + ": no releaseNotes")
148+
if not readme_name:
149+
fail(package + ": no readme")
150+
readme = ""
151+
else:
152+
try:
153+
readme = z.read(readme_name).decode("utf-8", "replace")
154+
except KeyError:
155+
fail("%s: readme %s not in the package" % (package, readme_name))
156+
readme = ""
157+
urls = []
158+
for source, body in (("projectUrl", project_url), ("repository", repo_url), ("releaseNotes", notes), ("README", readme)):
159+
for u in URL.findall(body):
160+
u = strip_trailing(u)
161+
if LOCAL.match(u):
162+
continue
163+
if u not in [x[1] for x in urls]:
164+
urls.append((source, u))
165+
print(" %d urls" % len(urls))
166+
for source, u in urls:
167+
s = status(u)
168+
ok = isinstance(s, int) and 200 <= s < 300
169+
print(" %s %s (%s)" % ("ok " if ok else "FAIL", u, source))
170+
if not ok:
171+
fail("%s: %s from %s -> %s" % (package, u, source, s))
172+
173+
174+
def check_obsoletions(version, workdir):
175+
print("== obsolete members in the published core assembly")
176+
scratch = os.path.join(workdir, "obsoletions")
177+
os.makedirs(scratch, exist_ok=True)
178+
with open(os.path.join(scratch, "Obsoletions.csproj"), "w", encoding="utf-8") as f:
179+
f.write(PROJECT.format(version=version))
180+
with open(os.path.join(scratch, "Program.cs"), "w", encoding="utf-8") as f:
181+
f.write(PROGRAM)
182+
with open(os.path.join(scratch, "nuget.config"), "w", encoding="utf-8") as f:
183+
f.write(NUGET_CONFIG)
184+
env = dict(os.environ, NUGET_PACKAGES=os.path.join(workdir, "packages"), DOTNET_CLI_TELEMETRY_OPTOUT="1", DOTNET_NOLOGO="1")
185+
run = subprocess.run(["dotnet", "run", "--project", scratch, "-c", "Release"], capture_output=True, text=True, env=env)
186+
if run.returncode != 0:
187+
fail("scratch project failed:\n" + run.stdout[-3000:] + run.stderr[-3000:])
188+
return
189+
seen = {}
190+
for line in run.stdout.splitlines():
191+
parts = line.strip().split("|")
192+
if parts[0] == "assembly":
193+
print(" " + parts[1])
194+
if "PublicKeyToken=null" in parts[1]:
195+
fail("core assembly is not strong-named: " + parts[1])
196+
continue
197+
if len(parts) != 4:
198+
continue
199+
member, diag_id, url_format, message = parts
200+
seen.setdefault(member, set()).add((diag_id, url_format))
201+
for member, expected in OBSOLETE.items():
202+
if member not in seen:
203+
fail(member + ": no ObsoleteAttribute found")
204+
continue
205+
for diag_id, url_format in seen[member]:
206+
if diag_id != expected:
207+
fail("%s: DiagnosticId %s, expected %s" % (member, diag_id, expected))
208+
continue
209+
if not url_format:
210+
fail(member + ": no UrlFormat")
211+
continue
212+
page = url_format.format(diag_id)
213+
anchor = page.split("#", 1)[1] if "#" in page else ""
214+
try:
215+
code, html = fetch(page.split("#", 1)[0])
216+
except urllib.error.HTTPError as e:
217+
fail("%s: %s -> %s" % (member, page, e.code))
218+
continue
219+
has_anchor = anchor and ('id="%s"' % anchor) in html
220+
print(" %s %s -> %s %s" % ("ok " if has_anchor else "FAIL", member, page, "anchor present" if has_anchor else "anchor missing"))
221+
if not has_anchor:
222+
fail("%s: anchor %s not in %s" % (member, anchor, page))
223+
224+
225+
def main():
226+
args = [a for a in sys.argv[1:] if not a.startswith("--")]
227+
keep = "--keep" in sys.argv
228+
if len(args) != 1:
229+
print(__doc__)
230+
sys.exit(2)
231+
version = args[0]
232+
workdir = tempfile.mkdtemp(prefix="jsonrpc-links-")
233+
try:
234+
for package in PACKAGES:
235+
check_package(package, version, workdir)
236+
check_obsoletions(version, workdir)
237+
finally:
238+
if keep:
239+
print("kept " + workdir)
240+
else:
241+
shutil.rmtree(workdir, ignore_errors=True)
242+
if failures:
243+
print("\n%d failure(s)" % len(failures))
244+
sys.exit(1)
245+
print("\nall package links and obsoletion anchors resolve for " + version)
246+
247+
248+
if __name__ == "__main__":
249+
main()

0 commit comments

Comments
 (0)