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
13 changes: 13 additions & 0 deletions .changeset/schedule-scope-by-name.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@executor-js/sdk": patch
"@executor-js/hosted-server": patch
"@executor-js/local-server": patch
---

Schedule configure and run now, by name, find app schedules without a scope. Run now takes an
optional `scope` (`app` or `user`), as configure does; it previously only looked for the caller's
own copy, so an app schedule was not found. Without `scope`, both routes act on the schedule saved
under the name, else on the app's declaration, else on the caller's copy as before. When both the
app schedule and the caller's copy are saved under the name, they fail with
`ScheduleScopeRequired` instead of guessing. Each scope keeps its authorization: only the app's
managers configure or run an app schedule. The SDK adds `schedules.scope`, which resolves it.
26 changes: 19 additions & 7 deletions apps/hosted/server/src/contracts/schedules.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/** Organization-aware schedule management, with browser-only human review. */
import { Context, Effect, Schema } from "effect";
import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api";
import {
AccountScope,
AppId,
Expand Down Expand Up @@ -43,13 +43,17 @@ const app = { ...organization, app: AppId };
const copy = { ...app, name: Schema.NonEmptyString, copy: ScheduleId };
const prefix = "/api/organizations/:organization";
const errors = [...ScheduleErrors, OrganizationForbidden, Forbidden] as const;
/** How a by-name route picks between the app schedule and the caller's copy; agents read it. */
const scopeRule =
"scope \"app\" is the app declaration's one schedule, which runs without a caller with the app's linked accounts; scope \"user\" is the caller's own copy of a user declaration. Without scope, the schedule saved under the name decides; with none saved, the app's declaration; otherwise user. When both the app schedule and the caller's copy are saved under the name, the call fails with ScheduleScopeRequired: retry with scope.";
/**
* App source owns timing/arguments. These routes only control schedule copies and review runs.
* Each member has at most one copy of a user declaration, which runs as that member with the app's
* linked accounts and the accounts they linked to it. An app declaration has one schedule, without
* an actor, which runs with the app's linked accounts and which only the app's managers control.
* Routes by name act on the caller's own copy, or with `scope: "app"` on the app schedule; routes
* by copy act on one copy, which its member, or someone who manages the app, controls.
* Routes by name act on the caller's own copy, or with `scope: "app"` on the app schedule, and
* without a scope resolve it by name; routes by copy act on one copy, which its member, or someone
* who manages the app, controls.
*/
export const HostedSchedules = HttpApiGroup.make("schedules")
.add(
Expand All @@ -74,21 +78,29 @@ export const HostedSchedules = HttpApiGroup.make("schedules")
approvalMode: Schema.optional(ScheduleApprovalMode),
/**
* `app` configures an app declaration's one schedule, which runs without a caller with
* the app's linked accounts and only its managers control; `user`, the default, the
* caller's own copy of a user declaration.
* the app's linked accounts and only its managers control; `user`, the caller's own copy
* of a user declaration. Omitted, the scope is resolved by name (see `scopeRule`).
*/
scope: Schema.optional(AccountScope),
}),
success: ScheduleSettings,
error: errors,
}),
}).annotate(
OpenApi.Description,
`Enable or pause a schedule by name, or set its approval mode. ${scopeRule} Only the app's managers configure an app schedule.`,
),
)
.add(
HttpApiEndpoint.post("runNow", `${prefix}/apps/:app/schedules/:name/run`, {
params: { ...app, name: Schema.NonEmptyString },
/** `app` runs the app schedule, `user` the caller's own copy; omitted, see `scopeRule`. */
query: { scope: Schema.optional(AccountScope) },
success: ScheduleSettings,
error: errors,
}),
}).annotate(
OpenApi.Description,
`Start an enabled schedule's run now, by name. ${scopeRule} Only the app's managers run an app schedule.`,
),
)
.add(
HttpApiEndpoint.patch("update", `${prefix}/apps/:app/schedules/:name/copies/:copy`, {
Expand Down
33 changes: 31 additions & 2 deletions apps/hosted/server/src/implementation/schedules.ts
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,23 @@ const runCopy = (executor: Executor, owner: OwnerId, copy: ScheduleSettings) =>
yield* wake;
return result;
});
/**
* The scope a by-name route acts on when the request names none. Only someone who may read the app,
* and so list its schedules, has it resolved; anyone else keeps the user scope, as before, and the
* route's own checks answer them.
*/
const resolvedScope = (
executor: Executor,
params: { readonly app: AppId; readonly name: string },
actor: string,
) =>
Effect.gen(function* () {
const owner = yield* appReaderOwner(params.app).pipe(
Effect.catchTag("OrganizationForbidden", () => Effect.succeed(undefined)),
);
if (owner === undefined) return "user" as const;
return yield* executor.schedules.scope({ ...params, owner, actor });
});
/** Shared handlers retain product ownership and reuse the existing browser approval contract. */
export const hostedScheduleHandlers = HttpApiBuilder.group(HostedApi, "schedules", (handlers) =>
handlers
Expand All @@ -152,7 +169,8 @@ export const hostedScheduleHandlers = HttpApiBuilder.group(HostedApi, "schedules
const executor = yield* Effect.flatten(HostedExecutor);
const actor = yield* CurrentUserId;
if (actor === undefined) return yield* new Forbidden();
const { scope, ...settings } = payload;
const { scope: requested, ...settings } = payload;
const scope = requested ?? (yield* resolvedScope(executor, params, actor));
if (scope === "app") {
// The app schedule runs without a caller, with the app's linked accounts; only the app's
// managers enable or pause it. The SDK refuses a declaration of the other scope.
Expand Down Expand Up @@ -181,11 +199,22 @@ export const hostedScheduleHandlers = HttpApiBuilder.group(HostedApi, "schedules
return result;
}),
)
.handle("runNow", ({ params }) =>
.handle("runNow", ({ params, query }) =>
Effect.gen(function* () {
const executor = yield* Effect.flatten(HostedExecutor);
const actor = yield* CurrentUserId;
if (actor === undefined) return yield* new Forbidden();
const scope = query.scope ?? (yield* resolvedScope(executor, params, actor));
if (scope === "app") {
// As configure: only the app's managers run the app schedule, which has no actor.
const owner = yield* appManagerOwner(params.app);
const copy = yield* executor.schedules.copy({
app: params.app,
name: params.name,
owner,
});
return yield* runCopy(executor, owner, copy);
}
const owner = yield* currentOwner;
yield* usableApp(executor, owner, params.app);
// The caller's own copy.
Expand Down
2 changes: 2 additions & 0 deletions apps/hosted/web/src/contracts/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ const errorMessage = Match.type<HostedError>().pipe(
ScheduleConflict: () =>
"The schedule is busy or changed. Check its current status and try again.",
ScheduleInvalid: () => "Update the interval or calendar timing in the app source.",
ScheduleScopeRequired: () =>
"Both the app schedule and your own copy have this name. Choose which one to change.",
GroupNotFound: () =>
"This group is unavailable or you do not have access. Ask an organization admin.",
GroupsUnavailable: () => "Groups could not be loaded or saved. Try again.",
Expand Down
20 changes: 15 additions & 5 deletions apps/local/server/src/contracts/schedules.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/** Local schedule controls use paired dashboard access and have no hosted organization fields. */
import { Schema } from "effect";
import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api";
import {
AccountScope,
AppId,
Expand All @@ -21,12 +21,16 @@ import {
const app = { app: AppId };
const copy = { ...app, name: Schema.NonEmptyString, copy: ScheduleId };
const prefix = "/dashboard/api";
/** How a by-name route picks between the app schedule and the local copy; agents read it. */
const scopeRule =
'scope "app" is the app declaration\'s one schedule, which runs without a caller with the app\'s linked accounts; scope "user" is your own copy of a user declaration. Without scope, the schedule saved under the name decides; with none saved, the app\'s declaration; otherwise user. When both the app schedule and your copy are saved under the name, the call fails with ScheduleScopeRequired: retry with scope.';
/**
* DashboardAccess is attached by the containing API to avoid a contract import cycle. User schedules
* run as the local subject, which has one copy of each user declaration and runs it with the app's
* linked accounts and the accounts linked to it. An app declaration has one schedule, without an
* actor, which runs with the app's linked accounts only. Routes by name act on the local subject's
* copy, or with `scope: "app"` on the app schedule; routes by copy act on one copy.
* copy, or with `scope: "app"` on the app schedule, and without a scope resolve it by name; routes
* by copy act on one copy.
*/
export const DashboardSchedules = HttpApiGroup.make("schedules")
.add(
Expand All @@ -51,20 +55,26 @@ export const DashboardSchedules = HttpApiGroup.make("schedules")
approvalMode: Schema.optional(ScheduleApprovalMode),
/**
* `app` configures an app declaration's one schedule, which runs without a caller with the
* app's linked accounts; `user`, the default, the local subject's copy of a user declaration.
* app's linked accounts; `user`, the local subject's copy of a user declaration. Omitted,
* the scope is resolved by name (see `scopeRule`).
*/
scope: Schema.optional(AccountScope),
}),
success: ScheduleSettings,
error: ScheduleErrors,
}),
}).annotate(
OpenApi.Description,
`Enable or pause a schedule by name, or set its approval mode. ${scopeRule}`,
),
)
.add(
HttpApiEndpoint.post("runNow", `${prefix}/apps/:app/schedules/:name/run`, {
params: { ...app, name: Schema.NonEmptyString },
/** `app` runs the app schedule, `user` the local subject's copy; omitted, see `scopeRule`. */
query: { scope: Schema.optional(AccountScope) },
success: ScheduleSettings,
error: ScheduleErrors,
}),
}).annotate(OpenApi.Description, `Start an enabled schedule's run now, by name. ${scopeRule}`),
)
.add(
HttpApiEndpoint.patch("update", `${prefix}/apps/:app/schedules/:name/copies/:copy`, {
Expand Down
29 changes: 20 additions & 9 deletions apps/local/server/src/implementation/schedules.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,18 +32,29 @@ export const localScheduleHandlers = (
),
),
)
// The app schedule has no actor; the SDK refuses a declaration of the other scope.
// The app schedule has no actor; the SDK refuses a declaration of the other scope. Without a
// scope, the saved schedule or else the declaration decides.
.handle("configure", ({ params, payload: { scope, ...settings } }) =>
executor.schedules.configure({
...params,
...settings,
...(scope === "app" ? {} : { actor: localActor }),
Effect.gen(function* () {
const resolved =
scope ?? (yield* executor.schedules.scope({ ...params, actor: localActor }));
return yield* executor.schedules.configure({
...params,
...settings,
...(resolved === "app" ? {} : { actor: localActor }),
});
}),
)
.handle("runNow", ({ params }) =>
executor.schedules
.copy({ ...params, actor: localActor })
.pipe(Effect.flatMap((copy) => executor.schedules.runNow({ ...params, copy: copy.id }))),
.handle("runNow", ({ params, query }) =>
Effect.gen(function* () {
const scope =
query.scope ?? (yield* executor.schedules.scope({ ...params, actor: localActor }));
const copy = yield* executor.schedules.copy({
...params,
...(scope === "app" ? {} : { actor: localActor }),
});
return yield* executor.schedules.runNow({ ...params, copy: copy.id });
}),
)
.handle("update", ({ params, payload }) =>
executor.schedules.update({ ...params, ...payload }),
Expand Down
5 changes: 5 additions & 0 deletions apps/local/web/src/contracts/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,11 @@ const errorMessage = Match.type<DashboardError>().pipe(
),
ScheduleInvalid: () =>
message("Invalid schedule", "Update the interval or calendar timing in the app source."),
ScheduleScopeRequired: () =>
message(
"Choose a schedule",
"Both the app schedule and your own copy have this name. Choose which one to change.",
),
RegistryError: (error) => message("Public app unavailable", registryErrorMessage(error)),
AppAccessDenied: () =>
message("Action unavailable", "You do not have permission to change this app."),
Expand Down
13 changes: 12 additions & 1 deletion e2e/test-plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7183,6 +7183,17 @@ export const scenarios = plan({
cloud: scheduled,
},
},
hostedAppScheduleScope: {
fixtures: "actors",
file: "app-schedules.spec.ts",
title:
"by-name schedule configure and run now without a scope resolve the app schedule or the caller's copy, refuse to guess when both are saved, and keep each scope's authorization",
targets: {
local: na("Hosted managers and members; Local app schedules have their own scenario."),
"self-host": scheduled,
cloud: scheduled,
},
},
hostedAppScopeWorkflows: {
fixtures: "actors",
file: "app-schedules.spec.ts",
Expand Down Expand Up @@ -8503,7 +8514,7 @@ export const scenarios = plan({
localAppScheduleAppLinks: {
file: "local-app-account-app-links.spec.ts",
title:
"a local app schedule runs with only the app's linked account and waits for one while none is linked",
"a local app schedule runs with only the app's linked account and waits for one while none is linked, and by-name run now and configure without a scope act on it",
targets: {
local: scheduled,
"self-host": na("Local app link routes; hosted app links have their own scenarios."),
Expand Down
Loading
Loading