Skip to content
Open
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
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ import {
isHttpMetadata,
shouldGenerateConvenient,
shouldGenerateProtocol,
updateUsageOrAccess,
UsageFlags,
} from "@azure-tools/typespec-client-generator-core";
import type { Diagnostic, Union } from "@typespec/compiler";
import {
Expand All @@ -54,6 +56,7 @@ import type {
InputLongRunningPagingServiceMethod,
InputLongRunningServiceMetadata,
InputLongRunningServiceMethod,
InputLroStatusMetadata,
InputNextLink,
InputPagingServiceMetadata,
InputPagingServiceMethod,
Expand All @@ -65,6 +68,8 @@ import type {
InputHeaderParameter,
InputHttpParameter,
InputMethodParameter,
InputModelProperty,
InputModelType,
InputPathParameter,
InputQueryParameter,
InputStreamingType,
Expand Down Expand Up @@ -725,6 +730,57 @@ function loadLongRunningMetadata(
method: SdkLroServiceMethod<SdkHttpOperation> | SdkLroPagingServiceMethod<SdkHttpOperation>,
): [InputLongRunningServiceMetadata, readonly Diagnostic[]] {
const diagnostics = createDiagnosticCollector();
const metadata = method.lroMetadata;

let pollingResponseModel: InputModelType | undefined;
let statusMetadata: InputLroStatusMetadata[] | undefined;
if (metadata.statusMetadata?.length) {
// Status metadata is read by deserializing the polling response with its generated deserializer,
// so the polling model graph must be emitted with JSON deserialization even when the polling
// operation itself is not exposed.
const pollingModel = metadata.pollingInfo.responseModel;
const outputTypes = new Set<SdkType>();
diagnostics.pipe(
updateUsageOrAccess(sdkContext, UsageFlags.Output | UsageFlags.Json, pollingModel, {
seenTypes: outputTypes,
}),
);
pollingResponseModel = diagnostics.pipe(fromSdkType(sdkContext, pollingModel));
for (const type of outputTypes) {
const inputType = sdkContext.__typeCache.types.get(type);
if (inputType?.kind === "model" || inputType?.kind === "enum") {
inputType.usage |= UsageFlags.Output | UsageFlags.Json;
}
}
Comment on lines +749 to +754

statusMetadata = [];
for (const entry of metadata.statusMetadata) {
const property = sdkContext.__typeCache.properties.get(entry.property);
const propertySegments = entry.propertySegments.map((segment) =>
sdkContext.__typeCache.properties.get(segment),
);
if (
property === undefined ||
propertySegments.length === 0 ||
propertySegments.some((segment) => segment === undefined)
) {
diagnostics.add(
createDiagnostic({
code: "general-error",
format: {
message: `Invalid LRO status metadata for '${method.name}': property '${entry.property.name}' is not a property of the polling response model '${pollingModel.name}'.`,
},
target: method.__raw ?? NoTarget,
}),
);
continue;
}
statusMetadata.push({
property,
propertySegments: propertySegments as InputModelProperty[],
});
}
}

return diagnostics.wrap({
finalStateVia: convertLroFinalStateVia(method.lroMetadata.finalStateVia),
Expand All @@ -740,6 +796,8 @@ function loadLongRunningMetadata(
: undefined,
} as OperationResponse,
resultPath: method.lroMetadata.finalResultPath,
pollingResponseModel,
statusMetadata,
});
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,13 @@
// Licensed under the MIT License. See License.txt in the project root for license information.

import type { InputOperation } from "./input-operation.js";
import type { InputMethodParameter, InputParameter, InputType } from "./input-type.js";
import type {
InputMethodParameter,
InputModelProperty,
InputModelType,
InputParameter,
InputType,
} from "./input-type.js";
import type { OperationFinalStateVia } from "./operation-final-state-via.js";
import type { OperationResponse } from "./operation-response.js";
import type { ResponseLocation } from "./response-location.js";
Expand Down Expand Up @@ -75,6 +81,17 @@ export interface InputLongRunningServiceMetadata {
finalStateVia: OperationFinalStateVia;
finalResponse: OperationResponse;
resultPath?: string;
/** The status-monitor (polling) response model. Present when `statusMetadata` is present. */
pollingResponseModel?: InputModelType;
/** Values selected by `@lroStatusMetadata` from the latest status-monitor response. */
statusMetadata?: InputLroStatusMetadata[];
}

export interface InputLroStatusMetadata {
/** The selected property of `pollingResponseModel` (or one of its base models). */
property: InputModelProperty;
/** Property path from `pollingResponseModel` to the selected value. */
propertySegments: InputModelProperty[];
}

export interface InputLongRunningPagingServiceMethod extends InputServiceMethodBase {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,15 @@
import type { TestHost } from "@typespec/compiler/testing";
import { UsageFlags } from "@azure-tools/typespec-client-generator-core";
import { deepStrictEqual, ok, strictEqual } from "assert";
import { readFileSync } from "node:fs";
import { beforeEach, describe, it } from "vitest";
import { serializeCodeModel } from "../../src/code-model-writer.js";
import { createModel } from "../../src/lib/client-model-builder.js";
import type { InputEnumType } from "../../src/type/input-type.js";
import type {
InputLongRunningServiceMethod,
InputLroStatusMetadata,
} from "../../src/type/input-service-method.js";
import type { InputEnumType, InputModelType } from "../../src/type/input-type.js";
import { RequestLocation } from "../../src/type/request-location.js";
import {
createCSharpSdkContext,
Expand Down Expand Up @@ -910,3 +916,199 @@ describe("Multipart convenience method generation", () => {
strictEqual(diagnostic, undefined);
});
});

// Source for generator/Microsoft.TypeSpec.Generator.Input/test/TestData/InputServiceMethodTests/LoadsEmittedLroStatusMetadata/tspCodeModel.json.
const lroStatusMetadataFixtureSource = `
import "@typespec/http";
import "@typespec/rest";
import "@azure-tools/typespec-azure-core";
import "@azure-tools/typespec-client-generator-core";

using TypeSpec.Http;
using TypeSpec.Rest;
using Azure.Core;
using Azure.ClientGenerator.Core;

@service
namespace LroFixture;

model Statistics {
completed: int32;
}

model BaseMonitor {
@lroStatusMetadata
@clientName("updatedAt")
@encodedName("application/json", "last_updated")
updated?: utcDateTime;
}

model Monitor extends BaseMonitor {
@lroStatus
status: "Running" | "Succeeded" | "Failed" | "Canceled";

@lroResult
result?: string;

@lroStatusMetadata
@clientName("progress")
@encodedName("application/json", "percent_complete")
percent?: int32;

@lroStatusMetadata
statistics?: Statistics;
}

@get
@route("/jobs/{jobId}/status")
op getStatus(@path jobId: string): Monitor;

@post
@route("/jobs")
@pollingOperation(getStatus)
op begin(): {
@statusCode code: 202;
@pollingLocation @header("Operation-Location") location: ResourceLocation<Monitor>;
};
`;

describe("LRO status metadata", () => {
let runner: TestHost;

beforeEach(async () => {
runner = await createEmitterTestHost();
});

function getLroMethod(root: ReturnType<typeof createModel>[0]): InputLongRunningServiceMethod {
const method = root.clients[0].methods.find((m) => m.kind === "lro");
ok(method);
return method as InputLongRunningServiceMethod;
}

it("emits the fixture consumed by the C# deserializer", async () => {
runner.addTypeSpecFile("main.tsp", lroStatusMetadataFixtureSource);
await runner.compile("./", { noEmit: true });
const sdkContext = await createCSharpSdkContext(createEmitterContext(runner.program));
const [root, diagnostics] = createModel(sdkContext);
deepStrictEqual(diagnostics, []);
const actual = JSON.parse(serializeCodeModel(sdkContext, root));
const expected = JSON.parse(
readFileSync(
new URL(
"../../../generator/Microsoft.TypeSpec.Generator.Input/test/TestData/InputServiceMethodTests/LoadsEmittedLroStatusMetadata/tspCodeModel.json",
import.meta.url,
),
"utf8",
),
);
deepStrictEqual(actual, expected);
});

it("references the polling model and its own properties in TCGC order", async () => {
runner.addTypeSpecFile("main.tsp", lroStatusMetadataFixtureSource);
await runner.compile("./", { noEmit: true });
const sdkContext = await createCSharpSdkContext(createEmitterContext(runner.program));
const [root] = createModel(sdkContext);
const metadata = getLroMethod(root).lroMetadata;
const monitor = root.models.find((m) => m.name === "Monitor");
const baseMonitor = root.models.find((m) => m.name === "BaseMonitor");
ok(monitor && baseMonitor);
strictEqual(metadata.pollingResponseModel, monitor);
const selections = metadata.statusMetadata as InputLroStatusMetadata[];
deepStrictEqual(
selections.map((s) => s.property.name),
["progress", "statistics", "updatedAt"],
);
strictEqual(
selections[0].property,
monitor.properties.find((p) => p.name === "progress"),
);
strictEqual(selections[2].property, baseMonitor.properties[0]);
for (const selection of selections) {
deepStrictEqual(selection.propertySegments, [selection.property]);
}
});

it("emits a polling model that is not exposed by a client method with JSON output usage", async () => {
const program = await typeSpecCompile(
`
model Details { message: string; }
model Monitor {
@lroStatus status: "Running" | "Succeeded" | "Failed" | "Canceled";
@lroStatusMetadata mode?: "fast" | "slow";
@lroStatusMetadata details?: Details;
}
@get @route("/jobs/{jobId}/status")
@scope("!csharp")
op getStatus(@path jobId: string): Monitor;
@post @route("/jobs")
@pollingOperation(getStatus)
op begin(): {
@statusCode code: 202;
@pollingLocation @header("Operation-Location") location: ResourceLocation<Monitor>;
};
`,
runner,
{ IsTCGCNeeded: true, IsAzureCoreNeeded: true },
);
const sdkContext = await createCSharpSdkContext(createEmitterContext(program));
const [root, diagnostics] = createModel(sdkContext);
deepStrictEqual(diagnostics, []);
strictEqual(root.clients[0].methods.length, 1);
const metadata = getLroMethod(root).lroMetadata;
const monitor = root.models.find((m) => m.name === "Monitor") as InputModelType;
const details = root.models.find((m) => m.name === "Details") as InputModelType;
ok(monitor && details);
strictEqual(metadata.pollingResponseModel, monitor);
for (const type of [monitor, details]) {
strictEqual(
type.usage & (UsageFlags.Output | UsageFlags.Json),
UsageFlags.Output | UsageFlags.Json,
);
}
const mode = metadata.statusMetadata?.[0].property.type as InputEnumType;
strictEqual(mode.kind, "enum");
ok(root.enums.includes(mode));
strictEqual(
mode.usage & (UsageFlags.Output | UsageFlags.Json),
UsageFlags.Output | UsageFlags.Json,
);

const serialized = JSON.parse(serializeCodeModel(sdkContext, root));
const serializedMetadata = serialized.clients[0].methods[0].lroMetadata;
strictEqual(serializedMetadata.statusMetadata.length, 2);
ok(serializedMetadata.pollingResponseModel.$ref);
});

it("does not emit status metadata when no property is selected", async () => {
const program = await typeSpecCompile(
`
model Monitor {
@lroStatus status: "Running" | "Succeeded" | "Failed" | "Canceled";
details?: string;
}
@get @route("/jobs/{jobId}/status")
op getStatus(@path jobId: string): Monitor;
@post @route("/jobs")
@pollingOperation(getStatus)
op begin(): {
@statusCode code: 202;
@pollingLocation @header("Operation-Location") location: ResourceLocation<Monitor>;
};
`,
runner,
{ IsTCGCNeeded: true, IsAzureCoreNeeded: true },
);
const sdkContext = await createCSharpSdkContext(createEmitterContext(program));
const [root] = createModel(sdkContext);
const metadata = getLroMethod(root).lroMetadata;
strictEqual(metadata.pollingResponseModel, undefined);
strictEqual(metadata.statusMetadata, undefined);
const serialized = JSON.parse(serializeCodeModel(sdkContext, root));
const serializedMetadata = serialized.clients[0].methods.find(
(m: { kind: string }) => m.kind === "lro",
).lroMetadata;
ok(!("pollingResponseModel" in serializedMetadata));
ok(!("statusMetadata" in serializedMetadata));
});
});
Original file line number Diff line number Diff line change
@@ -1,17 +1,26 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System.Collections.Generic;
using System.Linq;

namespace Microsoft.TypeSpec.Generator.Input
{
public sealed class InputLongRunningServiceMetadata
{
public InputLongRunningServiceMetadata(int finalStateVia, InputOperationResponse finalResponse, string? resultPath)
: this(finalStateVia, finalResponse, resultPath, null, [])
{
}

public InputLongRunningServiceMetadata(int finalStateVia, InputOperationResponse finalResponse, string? resultPath,
InputModelType? pollingResponseModel, IReadOnlyList<InputLroStatusMetadata> statusMetadata)
{
FinalStateVia = finalStateVia;
FinalResponse = finalResponse;
ResultPath = resultPath;
PollingResponseModel = pollingResponseModel;
StatusMetadata = statusMetadata;
}

public InputLongRunningServiceMetadata() : this(1, new InputOperationResponse(), null) { }
Expand All @@ -20,6 +29,17 @@ public InputLongRunningServiceMetadata(int finalStateVia, InputOperationResponse
public InputOperationResponse FinalResponse { get; }
public string? ResultPath { get; }

/// <summary>
/// The status-monitor (polling) response model. Present when <see cref="StatusMetadata"/> is not empty.
/// </summary>
public InputModelType? PollingResponseModel { get; }

/// <summary>
/// Values selected by <c>@lroStatusMetadata</c> from the latest status-monitor response.
/// Each selection refers to a property of <see cref="PollingResponseModel"/> or one of its base models.
/// </summary>
public IReadOnlyList<InputLroStatusMetadata> StatusMetadata { get; }

/// <summary>
/// Meaningful return type of the long running operation.
/// </summary>
Expand Down
Loading
Loading