[public-api, db, server, dashboard] Introduce MaintenanceNofitication banner that can be configured per org

Author: geropl

components/dashboard/src/AppNotifications.tsx

@@ -18,7 +18,8 @@ import { AttributionId } from "@gitpod/gitpod-protocol/lib/attribution";
 import { getGitpodService } from "./service/service";
 import { useOrgBillingMode } from "./data/billing-mode/org-billing-mode-query";
 import { Organization } from "@gitpod/public-api/lib/gitpod/v1/organization_pb";
-import { MaintenanceModeBanner } from "./components/MaintenanceModeBanner";
+import { MaintenanceModeBanner } from "./org-admin/MaintenanceModeBanner";
+import { ScheduledMaintenanceBanner } from "./org-admin/ScheduledMaintenanceBanner";
 
 const KEY_APP_DISMISSED_NOTIFICATIONS = "gitpod-app-notifications-dismissed";
 const PRIVACY_POLICY_LAST_UPDATED = "2024-12-03";
@@ -212,6 +213,7 @@ export function AppNotifications() {
     return (
         <div className="app-container pt-2">
             <MaintenanceModeBanner />
+            <ScheduledMaintenanceBanner />
             {topNotification && (
                 <Alert
                     type={topNotification.type}

components/dashboard/src/data/maintenance-notification-query.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCurrentOrg } from "./organizations/orgs-query";
+import { organizationClient } from "../service/public-api";
+import { MaintenanceNotification } from "@gitpod/gitpod-protocol";
+
+export const maintenanceNotificationQueryKey = (orgId: string) => ["maintenance-notification", orgId];
+
+export const useMaintenanceNotification = () => {
+    const { data: org } = useCurrentOrg();
+    const queryClient = useQueryClient();
+
+    const { data, isLoading } = useQuery<MaintenanceNotification>(
+        maintenanceNotificationQueryKey(org?.id || ""),
+        async () => {
+            if (!org?.id) return { enabled: false };
+
+            try {
+                const response = await organizationClient.getMaintenanceNotification({
+                    organizationId: org.id,
+                });
+                return {
+                    enabled: response.isEnabled,
+                    message: response.message,
+                };
+            } catch (error) {
+                console.error("Failed to fetch maintenance notification settings", error);
+                return { enabled: false };
+            }
+        },
+        {
+            enabled: !!org?.id,
+            staleTime: 30 * 1000, // 30 seconds
+            refetchInterval: 60 * 1000, // 1 minute
+        },
+    );
+
+    const setMaintenanceNotification = async (
+        isEnabled: boolean,
+        customMessage?: string,
+    ): Promise<MaintenanceNotification> => {
+        if (!org?.id) return { enabled: false, message: "" };
+
+        try {
+            const response = await organizationClient.setMaintenanceNotification({
+                organizationId: org.id,
+                isEnabled,
+                customMessage,
+            });
+
+            const result: MaintenanceNotification = {
+                enabled: response.isEnabled,
+                message: response.message,
+            };
+
+            // Update the cache
+            queryClient.setQueryData(maintenanceNotificationQueryKey(org.id), result);
+
+            return result;
+        } catch (error) {
+            console.error("Failed to set maintenance notification", error);
+            return { enabled: false };
+        }
+    };
+
+    return {
+        isNotificationEnabled: data?.enabled || false,
+        notificationMessage: data?.message,
+        isLoading,
+        setMaintenanceNotification,
+    };
+};

components/dashboard/src/org-admin/AdminPage.tsx

@@ -13,6 +13,7 @@ import Header from "../components/Header";
 import { SpinnerLoader } from "../components/Loader";
 import { RunningWorkspacesCard } from "./RunningWorkspacesCard";
 import { MaintenanceModeCard } from "./MaintenanceModeCard";
+import { MaintenanceNotificationCard } from "./MaintenanceNotificationCard";
 
 const AdminPage: React.FC = () => {
     const history = useHistory();
@@ -54,6 +55,7 @@ const AdminPage: React.FC = () => {
 
                 {currentOrg && (
                     <>
+                        <MaintenanceNotificationCard />
                         <MaintenanceModeCard />
                         <RunningWorkspacesCard />
                     </>

components/dashboard/src/components/MaintenanceModeBanner.tsx renamed to components/dashboard/src/org-admin/MaintenanceModeBanner.tsx

@@ -5,7 +5,7 @@
  */
 
 import { FC } from "react";
-import Alert from "./Alert";
+import Alert from "../components/Alert";
 import { useMaintenanceMode } from "../data/maintenance-mode-query";
 
 export const MaintenanceModeBanner: FC = () => {

components/dashboard/src/org-admin/MaintenanceNotificationCard.tsx

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { FC, useState, useEffect } from "react";
+import { useToast } from "../components/toasts/Toasts";
+import { Button } from "@podkit/buttons/Button";
+import { useMaintenanceNotification } from "../data/maintenance-notification-query";
+import Alert from "../components/Alert";
+
+export const MaintenanceNotificationCard: FC = () => {
+    const { isNotificationEnabled, notificationMessage, isLoading, setMaintenanceNotification } =
+        useMaintenanceNotification();
+    const [message, setMessage] = useState(notificationMessage);
+    const [isEditing, setIsEditing] = useState(false);
+    const toast = useToast();
+
+    // Update local state when the data from the API changes
+    useEffect(() => {
+        setMessage(notificationMessage);
+    }, [notificationMessage]);
+
+    const toggleNotification = async () => {
+        try {
+            const newState = !isNotificationEnabled;
+            const result = await setMaintenanceNotification(newState, message);
+
+            toast.toast({
+                message: `Maintenance notification ${result.enabled ? "enabled" : "disabled"}`,
+                type: "success",
+            });
+
+            setIsEditing(false);
+        } catch (error) {
+            console.error("Failed to toggle maintenance notification", error);
+            toast.toast({ message: "Failed to toggle maintenance notification", type: "error" });
+        }
+    };
+
+    const saveMessage = async () => {
+        try {
+            await setMaintenanceNotification(isNotificationEnabled, message);
+
+            toast.toast({
+                message: "Maintenance notification message updated",
+                type: "success",
+            });
+
+            setIsEditing(false);
+        } catch (error) {
+            console.error("Failed to update maintenance notification message", error);
+            toast.toast({ message: "Failed to update maintenance notification message", type: "error" });
+        }
+    };
+
+    return (
+        <div className="bg-white dark:bg-gray-800 shadow-md rounded-lg p-4 mb-4">
+            <div className="flex justify-between items-center mb-4">
+                <div>
+                    <h3 className="text-lg font-semibold text-gray-700 dark:text-gray-200">
+                        Scheduled Maintenance Notification
+                    </h3>
+                    <p className="text-gray-500 dark:text-gray-400">
+                        Display a notification banner to inform users about upcoming maintenance.
+                    </p>
+                </div>
+                <Button
+                    variant={isNotificationEnabled ? "secondary" : "default"}
+                    onClick={toggleNotification}
+                    disabled={isLoading}
+                >
+                    {isLoading ? "Loading..." : isNotificationEnabled ? "Disable" : "Enable"}
+                </Button>
+            </div>
+
+            {/* Message input section */}
+            <div className="mt-4">
+                <label
+                    htmlFor="maintenance-message"
+                    className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2"
+                >
+                    Notification Message
+                </label>
+                {isEditing ? (
+                    <div>
+                        <textarea
+                            id="maintenance-message"
+                            className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 dark:bg-gray-700 dark:text-white"
+                            rows={3}
+                            value={message}
+                            onChange={(e) => setMessage(e.target.value)}
+                            placeholder="Enter a message to display in the notification banner"
+                        />
+                        <div className="mt-2 flex justify-end space-x-2">
+                            <Button
+                                variant="secondary"
+                                onClick={() => {
+                                    setMessage(notificationMessage);
+                                    setIsEditing(false);
+                                }}
+                            >
+                                Cancel
+                            </Button>
+                            <Button onClick={saveMessage}>Save</Button>
+                        </div>
+                    </div>
+                ) : (
+                    <div>
+                        <div className="px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-md bg-gray-50 dark:bg-gray-700 text-gray-700 dark:text-gray-300 min-h-[4rem]">
+                            {message || (
+                                <span className="text-gray-400 dark:text-gray-500 italic">
+                                    Default message will be used
+                                </span>
+                            )}
+                        </div>
+                        <div className="mt-2 flex justify-end">
+                            <Button variant="secondary" onClick={() => setIsEditing(true)}>
+                                Edit Message
+                            </Button>
+                        </div>
+                    </div>
+                )}
+            </div>
+
+            {/* Preview section */}
+            {isNotificationEnabled && (
+                <div className="mt-4">
+                    <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Preview</label>
+                    <Alert type="warning" className="mb-0">
+                        <div className="flex items-center">
+                            <span className="font-semibold">Scheduled Maintenance:</span>
+                            <span className="ml-2">
+                                {message || "Maintenance is scheduled for this system. Please save your work."}
+                            </span>
+                        </div>
+                    </Alert>
+                </div>
+            )}
+        </div>
+    );
+};

components/dashboard/src/org-admin/ScheduledMaintenanceBanner.tsx

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { FC } from "react";
+import Alert from "../components/Alert";
+import { useMaintenanceNotification } from "../data/maintenance-notification-query";
+import { useMaintenanceMode } from "../data/maintenance-mode-query";
+
+export const ScheduledMaintenanceBanner: FC = () => {
+    const { isNotificationEnabled, notificationMessage } = useMaintenanceNotification();
+    const { isMaintenanceMode } = useMaintenanceMode();
+
+    // As per requirement R4.5, if both maintenance mode and scheduled notification
+    // are enabled, only show the maintenance mode notification
+    if (isMaintenanceMode || !isNotificationEnabled) {
+        return null;
+    }
+
+    const defaultMessage = "Maintenance is scheduled for this system. Please save your work.";
+    const displayMessage = notificationMessage || defaultMessage;
+
+    return (
+        <Alert type="warning" className="mb-2">
+            <div className="flex items-center">
+                <span className="font-semibold">Scheduled Maintenance:</span>
+                <span className="ml-2">{displayMessage}</span>
+            </div>
+        </Alert>
+    );
+};

components/dashboard/src/service/json-rpc-organization-client.ts

@@ -22,6 +22,8 @@ import {
     GetOrganizationResponse,
     GetOrganizationSettingsRequest,
     GetOrganizationSettingsResponse,
+    GetMaintenanceNotificationRequest,
+    GetMaintenanceNotificationResponse,
     JoinOrganizationRequest,
     JoinOrganizationResponse,
     ListOrganizationMembersRequest,
@@ -35,6 +37,8 @@ import {
     ResetOrganizationInvitationResponse,
     SetOrganizationMaintenanceModeRequest,
     SetOrganizationMaintenanceModeResponse,
+    SetMaintenanceNotificationRequest,
+    SetMaintenanceNotificationResponse,
     UpdateOrganizationMemberRequest,
     UpdateOrganizationMemberResponse,
     UpdateOrganizationRequest,
@@ -299,7 +303,7 @@ export class JsonRpcOrganizationClient implements PromiseClient<typeof Organizat
         }
         const result = await getGitpodService().server.getTeam(request.organizationId);
         return new GetOrganizationMaintenanceModeResponse({
-            enabled: result.maintenanceMode,
+            enabled: !!result.maintenanceMode,
         });
     }
 
@@ -314,7 +318,40 @@ export class JsonRpcOrganizationClient implements PromiseClient<typeof Organizat
             maintenanceMode: request.enabled,
         });
         return new SetOrganizationMaintenanceModeResponse({
-            enabled: result.maintenanceMode,
+            enabled: !!result.maintenanceMode,
+        });
+    }
+
+    async getMaintenanceNotification(
+        request: PartialMessage<GetMaintenanceNotificationRequest>,
+        options?: CallOptions | undefined,
+    ): Promise<GetMaintenanceNotificationResponse> {
+        if (!request.organizationId) {
+            throw new ApplicationError(ErrorCodes.BAD_REQUEST, "organizationId is required");
+        }
+        const result = await getGitpodService().server.getTeam(request.organizationId);
+        return new GetMaintenanceNotificationResponse({
+            isEnabled: result.maintenanceNotification?.enabled || false,
+            message: result.maintenanceNotification?.message || "",
+        });
+    }
+
+    async setMaintenanceNotification(
+        request: PartialMessage<SetMaintenanceNotificationRequest>,
+        options?: CallOptions | undefined,
+    ): Promise<SetMaintenanceNotificationResponse> {
+        if (!request.organizationId) {
+            throw new ApplicationError(ErrorCodes.BAD_REQUEST, "organizationId is required");
+        }
+        const result = await getGitpodService().server.updateTeam(request.organizationId, {
+            maintenanceNotification: {
+                enabled: !!request.isEnabled,
+                message: request.customMessage,
+            },
+        });
+        return new SetMaintenanceNotificationResponse({
+            isEnabled: result.maintenanceNotification?.enabled || false,
+            message: result.maintenanceNotification?.message || "",
         });
     }
 }

components/gitpod-db/src/team-db.ts

@@ -32,7 +32,10 @@ export interface TeamDB extends TransactionalDB<TeamDB> {
     findTeamsByUser(userId: string): Promise<Team[]>;
     findTeamsByUserAsSoleOwner(userId: string): Promise<Team[]>;
     createTeam(userId: string, name: string): Promise<Team>;
-    updateTeam(teamId: string, team: Partial<Pick<Team, "name" | "maintenanceMode">>): Promise<Team>;
+    updateTeam(
+        teamId: string,
+        team: Partial<Pick<Team, "name" | "maintenanceMode" | "maintenanceNotification">>,
+    ): Promise<Team>;
     addMemberToTeam(userId: string, teamId: string): Promise<"added" | "already_member">;
     setTeamMemberRole(userId: string, teamId: string, role: TeamMemberRole): Promise<void>;
     removeMemberFromTeam(userId: string, teamId: string): Promise<void>;

components/gitpod-db/src/typeorm/entity/db-team.ts

@@ -4,7 +4,7 @@
  * See License.AGPL.txt in the project root for license information.
  */
 
-import { Team } from "@gitpod/gitpod-protocol";
+import { MaintenanceNotification, Team } from "@gitpod/gitpod-protocol";
 import { Entity, Column, PrimaryColumn } from "typeorm";
 import { TypeORM } from "../typeorm";
 
@@ -28,4 +28,7 @@ export class DBTeam implements Team {
 
     @Column({ default: false })
     maintenanceMode?: boolean;
+
+    @Column("json", { nullable: true })
+    maintenanceNotification?: MaintenanceNotification;
 }