@contractkit/plugin-csharp 0.0.0

package/src/runtime-converters.ts

@@ -0,0 +1,147 @@
+/**
+ * The `Runtime/Converters.cs` file: the shared `JsonSerializerOptions` and the converters for the
+ * three ContractKit scalars whose BCL type does not serialize the way the contract says it travels.
+ *
+ * These live in the generated output rather than in a published NuGet package so the SDK has no
+ * dependency at all. The same choice the Python plugin makes with `_base_client.py` and the Kotlin
+ * plugin with `Serializers.kt`.
+ *
+ * Enums, unions and tuples are not handled here: each carries a `[JsonConverter]` attribute of its
+ * own, so it serializes correctly under any options. These three are options-level, which is why
+ * anything serializing a generated model by hand has to pass `SdkJson.Options`.
+ */
+
+/** Generate `Runtime/Converters.cs` for `namespaceName`. Content depends on nothing but the namespace. */
+export function generateConvertersCs(namespaceName: string): string {
+    return `// <auto-generated/>
+// Generated by @contractkit/plugin-csharp. Do not edit manually.
+#nullable enable
+
+using System;
+using System.Buffers;
+using System.Globalization;
+using System.Numerics;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Xml;
+
+namespace ${namespaceName}.Runtime;
+
+/// <summary>
+/// How the SDK reads and writes JSON.
+/// </summary>
+/// <remarks>
+/// Unknown properties are skipped, which is the default, so a service adding a field does not break
+/// an older client. Serialize a generated model with these options: three of the contract's scalar
+/// types need the converters registered here.
+/// </remarks>
+public static class SdkJson
+{
+    public static readonly JsonSerializerOptions Options = CreateOptions();
+
+    private static JsonSerializerOptions CreateOptions()
+    {
+        var options = new JsonSerializerOptions();
+        options.Converters.Add(new BigIntegerConverter());
+        options.Converters.Add(new DecimalStringConverter());
+        options.Converters.Add(new IsoTimeSpanConverter());
+        return options;
+    }
+}
+
+/// <summary>
+/// An arbitrary-precision integer. Written as a plain digit string.
+/// </summary>
+/// <remarks>
+/// Reading accepts a digit string, the <c>123n</c> form the TypeScript SDK writes, and a JSON
+/// number, so a body written by any ContractKit client reads back here.
+/// </remarks>
+public sealed class BigIntegerConverter : JsonConverter<BigInteger>
+{
+    public override BigInteger Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType == JsonTokenType.String)
+        {
+            var text = reader.GetString() ?? throw new JsonException("Expected a digit string for a bigint.");
+            return BigInteger.Parse(text.TrimEnd('n'), NumberStyles.Integer, CultureInfo.InvariantCulture);
+        }
+
+        if (reader.TokenType == JsonTokenType.Number)
+        {
+            // Read the raw token rather than a long: the value may be wider than any BCL integer,
+            // which is the whole reason the contract called it a bigint.
+            var raw = Encoding.UTF8.GetString(reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan);
+            return BigInteger.Parse(raw, NumberStyles.Integer, CultureInfo.InvariantCulture);
+        }
+
+        throw new JsonException($"Expected a JSON string or number for a bigint, got {reader.TokenType}.");
+    }
+
+    public override void Write(Utf8JsonWriter writer, BigInteger value, JsonSerializerOptions options)
+    {
+        writer.WriteStringValue(value.ToString(CultureInfo.InvariantCulture));
+    }
+}
+
+/// <summary>
+/// An exact decimal number. Travels as a quoted JSON string, never as a JSON number.
+/// </summary>
+/// <remarks>
+/// A JSON number has already been through a double by the time it reaches this converter, so the
+/// precision the contract asked for is gone. Reading an unquoted number is rejected for that
+/// reason, which matches the Kotlin SDK and the server's own schema.
+/// </remarks>
+public sealed class DecimalStringConverter : JsonConverter<decimal>
+{
+    public override decimal Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType != JsonTokenType.String)
+        {
+            throw new JsonException($"Expected a quoted decimal string, got {reader.TokenType}.");
+        }
+
+        var text = reader.GetString() ?? throw new JsonException("Expected a decimal string.");
+        return decimal.Parse(text, NumberStyles.Float, CultureInfo.InvariantCulture);
+    }
+
+    public override void Write(Utf8JsonWriter writer, decimal value, JsonSerializerOptions options)
+    {
+        writer.WriteStringValue(value.ToString(CultureInfo.InvariantCulture));
+    }
+}
+
+/// <summary>
+/// A duration, as an ISO 8601 string such as <c>PT1H30M</c>.
+/// </summary>
+/// <remarks>
+/// System.Text.Json writes a <c>TimeSpan</c> as <c>d.hh:mm:ss</c> by default, which no other
+/// ContractKit SDK would read, so this converter is not optional.
+/// </remarks>
+public sealed class IsoTimeSpanConverter : JsonConverter<TimeSpan>
+{
+    public override TimeSpan Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType != JsonTokenType.String)
+        {
+            throw new JsonException($"Expected an ISO 8601 duration string, got {reader.TokenType}.");
+        }
+
+        var text = reader.GetString() ?? throw new JsonException("Expected an ISO 8601 duration string.");
+        try
+        {
+            return XmlConvert.ToTimeSpan(text);
+        }
+        catch (FormatException error)
+        {
+            throw new JsonException($"'{text}' is not an ISO 8601 duration.", error);
+        }
+    }
+
+    public override void Write(Utf8JsonWriter writer, TimeSpan value, JsonSerializerOptions options)
+    {
+        writer.WriteStringValue(XmlConvert.ToString(value));
+    }
+}
+`;
+}

package/src/runtime.ts

@@ -0,0 +1,381 @@
+/**
+ * The `Runtime/SdkRuntime.cs` file: the `HttpClient` wrapper every generated client is built on.
+ *
+ * Nothing here comes from outside the BCL, so a generated SDK restores and builds with no NuGet
+ * feed at all. The TypeScript, Python and Kotlin SDKs likewise read and write their own bodies
+ * rather than delegating to a content-negotiation layer.
+ */
+
+/** Generate `Runtime/SdkRuntime.cs` for `namespaceName`. Content depends on nothing but the namespace. */
+export function generateRuntimeCs(namespaceName: string): string {
+    return `// <auto-generated/>
+// Generated by @contractkit/plugin-csharp. Do not edit manually.
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace ${namespaceName}.Runtime;
+
+/// <summary>
+/// How to reach the service.
+/// </summary>
+public sealed class SdkOptions
+{
+    /// <summary>Origin, optionally with a path prefix. Operation paths are appended to it.</summary>
+    public required string BaseUrl { get; init; }
+
+    /// <summary>
+    /// Called once per request. Authentication belongs here: returning a fresh map each time lets a
+    /// token be refreshed without rebuilding the SDK.
+    /// </summary>
+    public Func<CancellationToken, ValueTask<IReadOnlyDictionary<string, string>>>? Headers { get; init; }
+
+    /// <summary>
+    /// Supply your own client to control handlers, proxies or retries. When you do, the SDK never
+    /// disposes it. Leave it null and the SDK creates and owns one.
+    /// </summary>
+    public HttpClient? HttpClient { get; init; }
+
+    /// <summary>
+    /// How bodies, query values and headers are serialized. Defaults to <see cref="SdkJson.Options"/>,
+    /// which carries the converters the contract's scalar types need.
+    /// </summary>
+    public JsonSerializerOptions Json { get; init; } = SdkJson.Options;
+}
+
+/// <summary>
+/// A status the contract does not account for.
+/// </summary>
+/// <remarks>
+/// Derives from <see cref="HttpRequestException"/>, so it can be caught alongside any other client
+/// failure, and passes the status through to <c>StatusCode</c> for callers that catch the base type.
+/// </remarks>
+public class SdkException : HttpRequestException
+{
+    public SdkException(int status, string body, HttpResponseHeaders? responseHeaders = null, string? message = null)
+        : base(message ?? $"Request failed with status {status}", null, ToStatusCode(status))
+    {
+        Status = status;
+        Body = body;
+        ResponseHeaders = responseHeaders;
+    }
+
+    /// <summary>The HTTP status the service returned.</summary>
+    public int Status { get; }
+
+    /// <summary>The raw response body, read as UTF-8 text.</summary>
+    public string Body { get; }
+
+    /// <summary>The response headers, when the failure came from a response rather than a missing header.</summary>
+    public HttpResponseHeaders? ResponseHeaders { get; }
+
+    private bool _jsonParsed;
+    private JsonElement? _json;
+
+    /// <summary>
+    /// The body parsed as JSON, or null when it is not JSON. Error contracts usually are.
+    /// </summary>
+    public JsonElement? Json
+    {
+        get
+        {
+            if (_jsonParsed) return _json;
+            _jsonParsed = true;
+            try
+            {
+                using var document = JsonDocument.Parse(Body);
+                // Clone detaches the element from the document being disposed here.
+                _json = document.RootElement.Clone();
+            }
+            catch (JsonException)
+            {
+                _json = null;
+            }
+            return _json;
+        }
+    }
+
+    /// <summary>
+    /// Read the error body as <typeparamref name="T"/>, or null when it does not parse. Operations
+    /// whose thrown statuses declare a body generate an alias naming the type to use here.
+    /// </summary>
+    public T? TryReadBody<T>(JsonSerializerOptions? options = null)
+        where T : class
+    {
+        try
+        {
+            return JsonSerializer.Deserialize<T>(Body, options ?? SdkJson.Options);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    private static HttpStatusCode? ToStatusCode(int status) =>
+        status is >= 100 and <= 599 ? (HttpStatusCode)status : null;
+}
+
+/// <summary>
+/// One response, with its body already read.
+/// </summary>
+/// <remarks>
+/// Reading the body eagerly is what allows a generated method to check the status, then the content
+/// type, then decode, which is exactly what an operation declaring several statuses or several
+/// mimes has to do.
+/// </remarks>
+public sealed class SdkResponse
+{
+    private string? _text;
+
+    public SdkResponse(HttpResponseMessage message, byte[] bytes)
+    {
+        Message = message;
+        Bytes = bytes;
+    }
+
+    public HttpResponseMessage Message { get; }
+
+    /// <summary>The body as raw bytes.</summary>
+    public byte[] Bytes { get; }
+
+    public int Status => (int)Message.StatusCode;
+
+    /// <summary>The response mime without its parameters, so <c>application/json; charset=utf-8</c> matches.</summary>
+    public string ContentType => Message.Content.Headers.ContentType?.MediaType ?? string.Empty;
+
+    /// <summary>The body decoded as UTF-8.</summary>
+    public string Text => _text ??= Encoding.UTF8.GetString(Bytes);
+
+    /// <summary>
+    /// The first value of a response or content header, or null when the service did not send it.
+    /// </summary>
+    public string? Header(string name)
+    {
+        if (Message.Headers.TryGetValues(name, out var values)) return values.FirstOrDefault();
+        if (Message.Content.Headers.TryGetValues(name, out var contentValues)) return contentValues.FirstOrDefault();
+        return null;
+    }
+}
+
+/// <summary>
+/// One part of a multipart request body.
+/// </summary>
+public sealed record SdkPart(string Name, HttpContent Content, string? FileName = null)
+{
+    /// <summary>A plain text field.</summary>
+    public static SdkPart Text(string name, string value) => new(name, new StringContent(value, Encoding.UTF8));
+
+    /// <summary>A file field, sent with a filename and its own content type.</summary>
+    public static SdkPart File(string name, byte[] bytes, string fileName, string contentType = "application/octet-stream")
+    {
+        var content = new ByteArrayContent(bytes);
+        content.Headers.ContentType = new MediaTypeHeaderValue(contentType);
+        return new SdkPart(name, content, fileName);
+    }
+}
+
+/// <summary>
+/// Issues requests and turns anything the contract does not describe into an <see cref="SdkException"/>.
+/// </summary>
+/// <remarks>
+/// Every value bound for a path, query, header or form field is turned into text by serializing it
+/// the same way it would be serialized into a JSON body. That is what keeps a <c>Guid</c>, a
+/// <c>DateTimeOffset</c>, a <c>TimeSpan</c> or an enum spelled identically wherever it appears in a
+/// request, without a line of per-type code in the generator.
+/// </remarks>
+public sealed class SdkHttp : IDisposable
+{
+    private readonly SdkOptions _options;
+    private readonly bool _ownsClient;
+
+    public SdkHttp(SdkOptions options)
+    {
+        _options = options;
+        _ownsClient = options.HttpClient is null;
+        Client = options.HttpClient ?? new HttpClient();
+        Json = options.Json;
+    }
+
+    public HttpClient Client { get; }
+
+    public JsonSerializerOptions Json { get; }
+
+    /// <summary>
+    /// Send one request and read its body.
+    /// </summary>
+    /// <remarks>
+    /// <c>expectStatuses</c> carries the statuses the operation declares as outcomes rather than
+    /// failures, such as a 404 the contract gives a meaning. Everything outside 2xx and that set
+    /// throws.
+    /// </remarks>
+    /// <exception cref="SdkException">On a status the contract does not declare.</exception>
+    public async Task<SdkResponse> ExecuteAsync(
+        HttpMethod method,
+        string path,
+        IEnumerable<KeyValuePair<string, string>>? query = null,
+        IEnumerable<KeyValuePair<string, string>>? headers = null,
+        HttpContent? content = null,
+        IReadOnlyCollection<int>? expectStatuses = null,
+        CancellationToken cancellationToken = default)
+    {
+        using var request = new HttpRequestMessage(method, BuildUrl(path, query));
+        if (content is not null) request.Content = content;
+
+        if (_options.Headers is not null)
+        {
+            foreach (var entry in await _options.Headers(cancellationToken).ConfigureAwait(false))
+            {
+                request.Headers.TryAddWithoutValidation(entry.Key, entry.Value);
+            }
+        }
+
+        if (headers is not null)
+        {
+            foreach (var entry in headers)
+            {
+                request.Headers.TryAddWithoutValidation(entry.Key, entry.Value);
+            }
+        }
+
+        var message = await Client.SendAsync(request, HttpCompletionOption.ResponseContentRead, cancellationToken).ConfigureAwait(false);
+        var bytes = await message.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);
+        var response = new SdkResponse(message, bytes);
+
+        var status = response.Status;
+        if ((status < 200 || status > 299) && (expectStatuses is null || !expectStatuses.Contains(status)))
+        {
+            throw new SdkException(status, response.Text, message.Headers);
+        }
+
+        return response;
+    }
+
+    /// <summary>Decode a JSON response body.</summary>
+    /// <exception cref="SdkException">When the body is JSON null.</exception>
+    public T ReadJson<T>(SdkResponse response)
+    {
+        var value = JsonSerializer.Deserialize<T>(response.Bytes, Json);
+        if (value is null)
+        {
+            throw new SdkException(response.Status, response.Text, response.Message.Headers, "Response body was null");
+        }
+
+        return value;
+    }
+
+    /// <summary>
+    /// Read a response header the contract declares as required.
+    /// </summary>
+    /// <exception cref="SdkException">When the service did not send it, since the caller was promised a value.</exception>
+    public string RequireHeader(SdkResponse response, string name) =>
+        response.Header(name)
+        ?? throw new SdkException(response.Status, response.Text, response.Message.Headers, $"Response is missing the required header '{name}'");
+
+    /// <summary>Join path segments onto the base URL. Each segment is already escaped.</summary>
+    public string Path(params string[] segments) => segments.Length == 0 ? string.Empty : "/" + string.Join("/", segments);
+
+    /// <summary>The escaped text form of a single value, for use as a path segment.</summary>
+    public string Segment<T>(T value) => Uri.EscapeDataString(ScalarText(JsonSerializer.SerializeToElement(value, Json)) ?? string.Empty);
+
+    /// <summary>
+    /// Every property of <paramref name="value"/> as a key and value pair. A list property repeats
+    /// its key; a null property is omitted.
+    /// </summary>
+    public IEnumerable<KeyValuePair<string, string>> Params<T>(T value)
+    {
+        if (value is null) yield break;
+
+        var element = JsonSerializer.SerializeToElement(value, Json);
+        if (element.ValueKind != JsonValueKind.Object) yield break;
+
+        foreach (var property in element.EnumerateObject())
+        {
+            if (property.Value.ValueKind == JsonValueKind.Array)
+            {
+                foreach (var item in property.Value.EnumerateArray())
+                {
+                    if (ScalarText(item) is { } itemText) yield return new KeyValuePair<string, string>(property.Name, itemText);
+                }
+            }
+            else if (ScalarText(property.Value) is { } text)
+            {
+                yield return new KeyValuePair<string, string>(property.Name, text);
+            }
+        }
+    }
+
+    /// <summary>A JSON body. Sent as a buffered string so the request carries a Content-Length.</summary>
+    public HttpContent JsonContent<T>(T value, string mediaType) =>
+        new StringContent(JsonSerializer.Serialize(value, Json), Encoding.UTF8, mediaType);
+
+    /// <summary>A form-encoded body, built from the same property walk as the query string.</summary>
+    public HttpContent FormContent<T>(T value) => new FormUrlEncodedContent(Params(value));
+
+    /// <summary>A multipart body.</summary>
+    public HttpContent MultipartContent(IEnumerable<SdkPart> parts)
+    {
+        var content = new MultipartFormDataContent();
+        foreach (var part in parts)
+        {
+            if (part.FileName is null) content.Add(part.Content, part.Name);
+            else content.Add(part.Content, part.Name, part.FileName);
+        }
+
+        return content;
+    }
+
+    /// <summary>A text body with an explicit mime.</summary>
+    public HttpContent TextContent(string value, string mediaType) => new StringContent(value, Encoding.UTF8, mediaType);
+
+    /// <summary>A binary body with an explicit mime.</summary>
+    public HttpContent BinaryContent(byte[] value, string mediaType)
+    {
+        var content = new ByteArrayContent(value);
+        content.Headers.ContentType = new MediaTypeHeaderValue(mediaType);
+        return content;
+    }
+
+    /// <summary>The text a scalar JSON value travels as outside a body, or null when it is absent.</summary>
+    public static string? ScalarText(JsonElement element) =>
+        element.ValueKind switch
+        {
+            JsonValueKind.Null or JsonValueKind.Undefined => null,
+            JsonValueKind.String => element.GetString(),
+            JsonValueKind.True => "true",
+            JsonValueKind.False => "false",
+            _ => element.GetRawText(),
+        };
+
+    public void Dispose()
+    {
+        if (_ownsClient) Client.Dispose();
+    }
+
+    private string BuildUrl(string path, IEnumerable<KeyValuePair<string, string>>? query)
+    {
+        var builder = new StringBuilder(_options.BaseUrl.TrimEnd('/')).Append(path);
+        if (query is null) return builder.ToString();
+
+        var first = true;
+        foreach (var entry in query)
+        {
+            builder.Append(first ? '?' : '&');
+            first = false;
+            builder.Append(Uri.EscapeDataString(entry.Key)).Append('=').Append(Uri.EscapeDataString(entry.Value));
+        }
+
+        return builder.ToString();
+    }
+}
+`;
+}

package/src/scaffold.ts

@@ -0,0 +1,41 @@
+/**
+ * The project file a generated SDK needs to build on its own.
+ *
+ * Emitted with `ifAbsent`, so it is created once and then belongs to the user: a project will add a
+ * package id, a version, an analyzer set and a signing key of its own, and regenerating over that
+ * would throw the work away. Generated C# sources are rewritten every run; this is not.
+ */
+
+/**
+ * What the scaffold pins. One object so a bump is one edit.
+ *
+ * There is deliberately no dependency list to go with it: the generated SDK uses only
+ * `System.Text.Json` and `HttpClient` from the shared framework, so `dotnet build` restores with no
+ * NuGet feed reachable at all.
+ */
+export const SCAFFOLD_VERSIONS = {
+    targetFramework: 'net10.0',
+} as const;
+
+/**
+ * Generate `<SdkName>.csproj`.
+ *
+ * `ImplicitUsings` is off because generated files carry an explicit `using` block of their own, and
+ * leaving it on would make the output depend on the SDK's implicit set rather than on what the
+ * generator wrote.
+ */
+export function generateCsproj(namespaceName: string, sdkName: string): string {
+    return `<!-- Created once by @contractkit/plugin-csharp. Yours to edit: it is never regenerated. -->
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>${SCAFFOLD_VERSIONS.targetFramework}</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <RootNamespace>${namespaceName}</RootNamespace>
+    <AssemblyName>${sdkName}</AssemblyName>
+  </PropertyGroup>
+
+</Project>
+`;
+}