@hostlink/nuxt-light 1.77.2 → 1.78.0

package/README.md

@@ -79,6 +79,9 @@ export default defineNuxtConfig({
           infra: {
             baseURL: 'https://infra.example.com/graphql',
             audience: 'infra-api',
+            healthURL: 'https://infra.example.com/health',
+            healthTimeout: 3000,
+            unavailableMessage: 'Connect to the company network or VPN.',
           },
         },
       },
@@ -113,6 +116,38 @@ For example, the first request made by this table automatically requests a
 
 ```vue
 <L-Table client="business" model-name="Order" />
+
+
+### Client availability and menus
+
+When a client has a `healthURL`, nuxt-light checks it on startup, when the
+browser comes back online, and when the tab becomes visible. Menu items can
+declare that they require that client:
+
+
+```yaml
+- label: Servers
+  icon: sym_o_dns
+  to: /Server
+  permission: server.list
+  requiresClient: infra
+```
+
+
+`L-Menu` keeps the authorized item visible, but disables it and shows the
+configured message while the client is checking or unavailable. Applications
+can use the same state for route guards or page notices:
+
+
+```ts
+const availability = useLightClientAvailability()
+
+if (!availability.isAvailable('infra')) {
+  // Show a company-network/VPN notice.
+}
+```
+
+Clients without a `healthURL` remain available and keep the previous behavior.
 ```
 
 ### Backwards-compatible single endpoint

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "light",
   "configKey": "light",
-  "version": "1.77.2",
+  "version": "1.78.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/L/Menu.vue

@@ -2,8 +2,18 @@
 import { useRoute } from "vue-router";
 import { ref, computed } from "vue";
 import { useLight } from "#imports";
+import useLightClientAvailability from "../../composables/useLightClientAvailability";
 const props = defineProps(["value", "dense", "expandAll"]);
 const light = useLight();
+const availability = useLightClientAvailability();
+const requiredClient = (menu) => typeof menu?.requiresClient === "string" ? menu.requiresClient : void 0;
+const isMenuAvailable = (menu) => availability.isAvailable(requiredClient(menu));
+const availabilityMessage = (menu) => {
+  const client = requiredClient(menu);
+  if (!client) return "";
+  if (availability.isChecking(client)) return "Checking service availability\u2026";
+  return availability.message(client);
+};
 const isShowExpansionItem = (menu) => {
   if (menu.children && menu.children.length > 0) {
     return true;
@@ -48,6 +58,7 @@ const hasChildLink = () => {
         <template v-for="menu in value">
 
             <q-expansion-item :default-opened="expandAll || hasLink(menu)" :label="$t(menu.label)" :icon="menu.icon" :dense="dense"
+                :disable="!isMenuAvailable(menu)" :caption="!isMenuAvailable(menu) ? availabilityMessage(menu) : undefined"
                 v-if="isShowExpansionItem(menu)" :group="expandAll ? undefined : group">
                 <l-menu class="q-pl-md" :value="menu.children" :dense="dense" :expand-all="expandAll"></l-menu>
             </q-expansion-item>
@@ -56,20 +67,34 @@ const hasChildLink = () => {
                 <q-separator v-if="menu.type == 'separator'" :spaced="menu.spaced" />
                 <q-item-label header v-if="menu.type == 'header'">{{ menu.label }}</q-item-label>
                 <template v-if="menu.to && (menu.to.startsWith('http://') || menu.to.startsWith('https://'))">
-                    <q-item v-ripple :href="menu.to" v-if="!value.type" target="_blank">
+                    <q-item v-ripple :href="isMenuAvailable(menu) ? menu.to : undefined" v-if="!value.type" target="_blank"
+                        :disable="!isMenuAvailable(menu)">
                         <q-item-section avatar>
                             <q-icon :name="menu.icon"  />
                         </q-item-section>
-                        <q-item-section>{{ $t(menu.label) }}</q-item-section>
+                        <q-item-section>
+                            {{ $t(menu.label) }}
+                            <q-item-label v-if="!isMenuAvailable(menu)" caption>{{ availabilityMessage(menu) }}</q-item-label>
+                        </q-item-section>
+                        <q-item-section v-if="!isMenuAvailable(menu)" side>
+                            <q-icon name="sym_o_vpn_lock"><q-tooltip>{{ availabilityMessage(menu) }}</q-tooltip></q-icon>
+                        </q-item-section>
                     </q-item>
                 </template>
 
                 <template v-else>
-                    <q-item v-ripple :to="menu.to" v-if="!value.type">
+                    <q-item v-ripple :to="isMenuAvailable(menu) ? menu.to : undefined" v-if="!value.type"
+                        :disable="!isMenuAvailable(menu)">
                         <q-item-section avatar>
                             <q-icon :name="menu.icon"  />
                         </q-item-section>
-                        <q-item-section>{{ $t(menu.label) }}</q-item-section>
+                        <q-item-section>
+                            {{ $t(menu.label) }}
+                            <q-item-label v-if="!isMenuAvailable(menu)" caption>{{ availabilityMessage(menu) }}</q-item-label>
+                        </q-item-section>
+                        <q-item-section v-if="!isMenuAvailable(menu)" side>
+                            <q-icon name="sym_o_vpn_lock"><q-tooltip>{{ availabilityMessage(menu) }}</q-tooltip></q-icon>
+                        </q-item-section>
                     </q-item>
                 </template>
 

package/dist/runtime/composables/useLightClientAvailability.d.ts

@@ -0,0 +1,30 @@
+export type LightClientAvailabilityStatus = 'checking' | 'available' | 'unavailable';
+export interface LightClientAvailabilityOptions {
+    healthURL?: string;
+    healthTimeout?: number;
+    unavailableMessage?: string;
+}
+export interface LightClientAvailabilityState {
+    status: LightClientAvailabilityStatus;
+    message: string;
+    checkedAt: number | null;
+}
+export declare function registerLightClientAvailability(name: string, config?: LightClientAvailabilityOptions): void;
+export declare function clearLightClientAvailability(): void;
+export declare function checkLightClientAvailability(name: string): Promise<LightClientAvailabilityStatus>;
+export declare function checkAllLightClientAvailability(): Promise<void>;
+export default function useLightClientAvailability(): {
+    states: {
+        readonly [x: string]: {
+            readonly status: LightClientAvailabilityStatus;
+            readonly message: string;
+            readonly checkedAt: number | null;
+        };
+    };
+    status: (name?: string) => LightClientAvailabilityStatus;
+    isAvailable: (name?: string) => boolean;
+    isChecking: (name?: string) => boolean;
+    message: (name?: string) => string;
+    check: typeof checkLightClientAvailability;
+    checkAll: typeof checkAllLightClientAvailability;
+};

package/dist/runtime/composables/useLightClientAvailability.js

@@ -0,0 +1,88 @@
+import { reactive, readonly } from "vue";
+const DEFAULT_TIMEOUT = 3e3;
+const DEFAULT_MESSAGE = "This service is currently unavailable.";
+const options = /* @__PURE__ */ new Map();
+const checks = /* @__PURE__ */ new Map();
+const states = reactive({});
+export function registerLightClientAvailability(name, config = {}) {
+  options.set(name, config);
+  states[name] = {
+    status: config.healthURL ? "checking" : "available",
+    message: "",
+    checkedAt: null
+  };
+}
+export function clearLightClientAvailability() {
+  options.clear();
+  checks.clear();
+  Object.keys(states).forEach((name) => delete states[name]);
+}
+export async function checkLightClientAvailability(name) {
+  const config = options.get(name);
+  if (!config) {
+    states[name] = {
+      status: "unavailable",
+      message: `Light client "${name}" is not configured.`,
+      checkedAt: Date.now()
+    };
+    return "unavailable";
+  }
+  if (!config.healthURL) {
+    states[name] = { status: "available", message: "", checkedAt: Date.now() };
+    return "available";
+  }
+  const checkId = (checks.get(name) ?? 0) + 1;
+  checks.set(name, checkId);
+  states[name] = { ...states[name], status: "checking", message: "" };
+  const controller = new AbortController();
+  const timeout = globalThis.setTimeout(
+    () => controller.abort(),
+    Math.max(1, config.healthTimeout ?? DEFAULT_TIMEOUT)
+  );
+  try {
+    const response = await fetch(config.healthURL, {
+      method: "GET",
+      cache: "no-store",
+      credentials: "omit",
+      signal: controller.signal
+    });
+    const status = response.ok ? "available" : "unavailable";
+    if (checks.get(name) === checkId) {
+      states[name] = {
+        status,
+        message: response.ok ? "" : config.unavailableMessage ?? DEFAULT_MESSAGE,
+        checkedAt: Date.now()
+      };
+    }
+    return status;
+  } catch {
+    if (checks.get(name) === checkId) {
+      states[name] = {
+        status: "unavailable",
+        message: config.unavailableMessage ?? DEFAULT_MESSAGE,
+        checkedAt: Date.now()
+      };
+    }
+    return "unavailable";
+  } finally {
+    globalThis.clearTimeout(timeout);
+  }
+}
+export async function checkAllLightClientAvailability() {
+  await Promise.all([...options.keys()].map((name) => checkLightClientAvailability(name)));
+}
+export default function useLightClientAvailability() {
+  const status = (name) => {
+    if (!name) return "available";
+    return states[name]?.status ?? "unavailable";
+  };
+  return {
+    states: readonly(states),
+    status,
+    isAvailable: (name) => status(name) === "available",
+    isChecking: (name) => status(name) === "checking",
+    message: (name) => name ? states[name]?.message ?? `Light client "${name}" is not configured.` : "",
+    check: checkLightClientAvailability,
+    checkAll: checkAllLightClientAvailability
+  };
+}

package/dist/runtime/plugin.js

@@ -13,19 +13,28 @@ import { plugin, defaultConfig } from "@formkit/vue";
 import getApiBase from "./composables/getApiBase.js";
 import useLight from "./composables/useLight.js";
 import useLightClient, { clearLightClients, registerLightClient } from "./composables/useLightClient.js";
+import {
+  checkAllLightClientAvailability,
+  checkLightClientAvailability,
+  clearLightClientAvailability,
+  registerLightClientAvailability
+} from "./composables/useLightClientAvailability.js";
 import { zhTW } from "@formkit/i18n";
 export default defineNuxtPlugin((nuxtApp) => {
   const runtimeConfig = useRuntimeConfig();
   const lightConfig = runtimeConfig.public.light;
   const configuredClients = lightConfig?.clients ?? {};
   clearLightClients();
+  clearLightClientAvailability();
   for (const [name, config] of Object.entries(configuredClients)) {
     const baseURL = typeof config === "string" ? config : config.baseURL;
     if (!baseURL) throw new Error(`Light client "${name}" requires a baseURL`);
     registerLightClient(name, createClient(baseURL));
+    registerLightClientAvailability(name, typeof config === "string" ? {} : config);
   }
   if (!configuredClients.auth) {
     registerLightClient("auth", createClient(getApiBase()));
+    registerLightClientAvailability("auth");
   }
   const authClient = useLightClient();
   setApiClient(authClient);
@@ -33,6 +42,21 @@ export default defineNuxtPlugin((nuxtApp) => {
     if (name === "auth" || typeof config === "string" || !config.audience) continue;
     useLightClient(name).useAudience(authClient, config.audience);
   }
+  if (import.meta.client) {
+    for (const name of Object.keys(configuredClients)) {
+      void checkLightClientAvailability(name);
+    }
+    const recheckClients = () => void checkAllLightClientAvailability();
+    const recheckVisibleClients = () => {
+      if (document.visibilityState === "visible") recheckClients();
+    };
+    window.addEventListener("online", recheckClients);
+    document.addEventListener("visibilitychange", recheckVisibleClients);
+    nuxtApp.hook("app:unmounted", () => {
+      window.removeEventListener("online", recheckClients);
+      document.removeEventListener("visibilitychange", recheckVisibleClients);
+    });
+  }
   defineModel("Permission", {}).setDataPath("app.listPermission");
   defineModel("SystemValue", {}).setDataPath("app.listSystemValue");
   defineModel("Config", {}).setDataPath("app.listConfig");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostlink/nuxt-light",
-  "version": "1.77.2",
+  "version": "1.78.0",
   "description": "HostLink Nuxt Light Framework",
   "repository": {
     "type": "git",