Skip to content

Commit f0a7f13

Browse files
committed
AUS-1013: package-link check, API surface dumps and an upgrading note
.github/scripts/check_package_links.py <version> downloads the four packages from nuget.org, requests every absolute URL in projectUrl, the repository url, the release notes and the README, and builds a scratch project that prints the ObsoleteAttribute on the three obsolete members so each UrlFormat, formatted with its DiagnosticId, is fetched and its anchor asserted in the page. Sample addresses (localhost, 127.0.0.1, .test, example.com) in the READMEs are skipped. .github/scripts/api_surface dumps the public API of the four assemblies as sorted text; docs/api-surface holds the dumps for 2.0.0-preview.1 and 2.0.0-preview.3. The preview.3 file is the surface frozen for 2.0.0. docs/upgrading.md gains the one step the upgrade smoke test needed that the guide did not state: Newtonsoft.Json is no longer a dependency of the core, so code that handles JObject or JArray adds the Newtonsoft package and selects its serializer.
1 parent 42b736a commit f0a7f13

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)