@dxos/edge-client 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,27 +16,27 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/neutral/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./cors-proxy": {
       "source": "./src/cors-proxy.ts",
       "types": "./dist/types/src/cors-proxy.d.ts",
-      "default": "./dist/lib/neutral/cors-proxy.mjs"
+      "import": "./dist/lib/cors-proxy.mjs"
     },
     "./muxer": {
       "source": "./src/edge-ws-muxer.ts",
       "types": "./dist/types/src/edge-ws-muxer.d.ts",
-      "default": "./dist/lib/neutral/edge-ws-muxer.mjs"
+      "import": "./dist/lib/edge-ws-muxer.mjs"
     },
     "./service": {
       "source": "./src/service/index.ts",
       "types": "./dist/types/src/service/index.d.ts",
-      "default": "./dist/lib/neutral/service/index.mjs"
+      "import": "./dist/lib/service.mjs"
     },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
-      "default": "./dist/lib/neutral/testing/index.mjs"
+      "import": "./dist/lib/testing.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -50,22 +50,22 @@
     "@opentelemetry/api": "^1.9.1",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.17.1",
-    "@dxos/async": "0.10.0",
-    "@dxos/effect": "0.10.0",
-    "@dxos/context": "0.10.0",
-    "@dxos/errors": "0.10.0",
-    "@dxos/crypto": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/keyring": "0.10.0",
-    "@dxos/keys": "0.10.0",
-    "@dxos/node-std": "0.10.0",
-    "@dxos/protocols": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/util": "0.10.0",
-    "@dxos/credentials": "0.10.0"
+    "@dxos/async": "0.11.0",
+    "@dxos/context": "0.11.0",
+    "@dxos/credentials": "0.11.0",
+    "@dxos/crypto": "0.11.0",
+    "@dxos/errors": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/keyring": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/protocols": "0.11.0",
+    "@dxos/node-std": "0.11.0",
+    "@dxos/util": "0.11.0"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.10.0"
+    "@dxos/test-utils": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4"

package/src/base-http-client.ts

@@ -53,6 +53,14 @@ type HttpRequestArgs = {
   auth?: boolean;
 };
 
+export type RawHttpRequestArgs = {
+  method: string;
+  body?: BodyInit;
+  headers?: Record<string, string>;
+  retry?: RetryConfig;
+  auth?: boolean;
+};
+
 export abstract class BaseHttpClient {
   protected readonly _baseUrl: string;
   protected readonly _clientTag: string | undefined;
@@ -77,9 +85,6 @@ export abstract class BaseHttpClient {
     }
   }
 
-  // TODO(mykola): Extend `_call` to support streaming/raw `Response` returns so
-  // `EdgeHttpClient.anthropicAiRequest` can be absorbed here and the auth/retry loop
-  // stops being duplicated across the two paths.
   protected async _call<T>(ctx: Context, url: URL, args: HttpRequestArgs): Promise<T> {
     const shouldRetry = createRetryHandler(args);
     // Log presence/size only — never log raw body contents which may contain PII.
@@ -162,6 +167,69 @@ export abstract class BaseHttpClient {
     }
   }
 
+  /**
+   * Like {@link _call} but returns the raw `Response` instead of parsing a JSON envelope — for
+   * endpoints with binary or absent response bodies (e.g. blob storage). A 404 is returned to the
+   * caller rather than thrown, since "not found" is an expected outcome for lookups; all other
+   * non-ok, non-retryable statuses throw `EdgeCallFailedError`, mirroring `_call`.
+   *
+   * NOTE: Duplicates `_call`'s auth/retry loop rather than sharing it, to avoid touching `_call`'s
+   * broadly-depended-on JSON-envelope behavior. `EdgeHttpClient.anthropicAiRequest`'s separate
+   * duplicate loop is a follow-up candidate for consolidating onto this method.
+   */
+  protected async _callRaw(ctx: Context, url: URL, args: RawHttpRequestArgs): Promise<Response> {
+    const shouldRetry = createRetryHandler(args);
+    log('fetch', { url, hasBody: args.body !== undefined });
+
+    const traceHeaders = getTraceHeaders(ctx);
+
+    let handledAuth = false;
+    while (true) {
+      let processingError: EdgeCallFailedError | undefined;
+      try {
+        if (!this._authHeader && args.auth) {
+          const response = await fetch(new URL('/auth', this._baseUrl));
+          if (response.status === 401) {
+            this._authHeader = await this._handleUnauthorized(response);
+          }
+        }
+
+        const headers: Record<string, string> = { ...args.headers };
+        if (this._authHeader) {
+          headers['Authorization'] = this._authHeader;
+        }
+        if (traceHeaders) {
+          Object.assign(headers, traceHeaders);
+        }
+        if (this._clientTag) {
+          headers[EDGE_CLIENT_TAG_HEADER] = this._clientTag;
+        }
+
+        const response = await fetch(url, { method: args.method, body: args.body, headers });
+
+        if (response.ok || response.status === 404) {
+          return response;
+        }
+
+        if (response.status === 401 && response.headers.get('WWW-Authenticate') !== null && !handledAuth) {
+          this._authHeader = await this._handleUnauthorized(response);
+          handledAuth = true;
+          continue;
+        }
+
+        processingError = await EdgeCallFailedError.fromHttpFailure(response);
+      } catch (error: any) {
+        processingError = EdgeCallFailedError.fromProcessingFailureCause(error);
+      }
+
+      if (processingError?.isRetryable && (await shouldRetry(ctx, processingError.retryAfterMs))) {
+        log.verbose('retrying raw request', { url, processingError });
+      } else {
+        throw processingError!;
+      }
+    }
+  }
+
   protected async _handleUnauthorized(response: Response): Promise<string> {
     if (!this._edgeIdentity) {
       log.warn('unauthorized response received before identity was set');

package/src/browser-rendering.ts

@@ -2,11 +2,8 @@
 // Copyright 2026 DXOS.org
 //
 
-import * as Context from 'effect/Context';
 import * as Schema from 'effect/Schema';
 
-import { type EdgeHttpClient } from './edge-http-client';
-
 /** Request body for EDGE `/ai/browser-rendering/markdown` (ai-service Browser Run markdown quick action). */
 export const MarkdownRequest = Schema.Struct({
   url: Schema.optional(Schema.String),
@@ -31,9 +28,3 @@ export const MarkdownResponse = Schema.Struct({
 });
 
 export type MarkdownResponse = Schema.Schema.Type<typeof MarkdownResponse>;
-
-/** Authenticated EDGE HTTP client for operation handlers (e.g. browser markdown fetch). */
-export class EdgeHttpClientService extends Context.Tag('@dxos/edge-client/EdgeHttpClientService')<
-  EdgeHttpClientService,
-  EdgeHttpClient
->() {}

package/src/edge-client.ts

@@ -2,6 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
+import * as EffectContext from 'effect/Context';
+
 import {
   Event,
   PersistentLifecycle,
@@ -51,9 +53,25 @@ export interface EdgeConnection extends Required<Lifecycle> {
   setIdentity(identity: EdgeIdentity): void;
   send(ctx: Context, message: Message): Promise<void>;
   onMessage(listener: MessageListener): () => void;
-  onReconnected(listener: ReconnectListener): () => void;
+  /**
+   * Subscribe to connection (re-)establishment.
+   *
+   * By default the listener also fires once immediately when the connection is already ready at
+   * subscription time — a current-state notification for late subscribers. Pass
+   * `emitCurrentState: false` for reconnect-reaction logic (e.g. restarting a session): reacting
+   * to the subscribe-time firing there causes restart loops, since each restart re-subscribes.
+   */
+  onReconnected(listener: ReconnectListener, opts?: { emitCurrentState?: boolean }): () => void;
 }
 
+/**
+ * Effect service tag for {@link EdgeConnection}.
+ */
+export class EdgeConnectionService extends EffectContext.Tag('@dxos/edge-client/EdgeConnection')<
+  EdgeConnectionService,
+  EdgeConnection
+>() {}
+
 /**
  * Messenger client for EDGE:
  *  - While open, uses PersistentLifecycle to keep an open EdgeWsConnection, reconnecting on failures.
@@ -165,9 +183,9 @@ export class EdgeClient extends Resource implements EdgeConnection {
     return () => this._messageListeners.delete(listener);
   }
 
-  public onReconnected(listener: ReconnectListener) {
+  public onReconnected(listener: ReconnectListener, opts?: { emitCurrentState?: boolean }) {
     this._reconnectListeners.add(listener);
-    if (this._ready.state === TriggerState.RESOLVED) {
+    if ((opts?.emitCurrentState ?? true) && this._ready.state === TriggerState.RESOLVED) {
       // Microtask so that listener is always called asynchronously, no matter the state of the ready trigger
       // at the moment of registration.
       scheduleMicroTask(this._ctx, () => {

package/src/edge-http-client.test.ts

@@ -4,8 +4,12 @@
 
 import { afterEach, describe, it, test, vi } from 'vitest';
 
+import { Context } from '@dxos/context';
+import { type Presentation } from '@dxos/protocols/proto/dxos/halo/credentials';
+
 import { createEphemeralEdgeIdentity } from './auth';
 import { EdgeHttpClient } from './edge-http-client';
+import { type EdgeIdentity } from './edge-identity';
 
 // TODO(burdon): Factor out config.
 const DEV_SERVER = 'https://edge.dxos.workers.dev';
@@ -54,3 +58,120 @@ describe('EdgeHttpClient.anthropicAiRequest', () => {
     expect(targetCall![1]?.method).toBe('POST');
   });
 });
+
+describe('EdgeHttpClient blobs', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  test('getBlobUrl URL-encodes the key', ({ expect }) => {
+    const client = new EdgeHttpClient('https://edge.example.com');
+    expect(client.getBlobUrl('abc123').toString()).toBe('https://edge.example.com/api/file/abc123');
+    expect(client.getBlobUrl('a/b/../c').toString()).toBe('https://edge.example.com/api/file/a%2Fb%2F..%2Fc');
+  });
+
+  test('putBlob sends a raw POST body and pre-fetches /auth', async ({ expect }) => {
+    const fetchMock = vi.fn(async (input: any, _init?: RequestInit) => {
+      const url = String(input instanceof URL ? input : (input.url ?? input));
+      if (url.endsWith('/auth')) {
+        return new Response(null, { status: 200 });
+      }
+      return new Response(null, { status: 200 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    const bytes = new Uint8Array([1, 2, 3]);
+    await client.putBlob(Context.default(), 'abc123', bytes, { contentType: 'application/octet-stream' });
+
+    const authCall = fetchMock.mock.calls.find((call) => String(call[0]).endsWith('/auth'));
+    expect(authCall).toBeDefined();
+
+    const putCall = fetchMock.mock.calls.find((call) => String(call[0]).includes('/api/file/abc123'));
+    expect(putCall).toBeDefined();
+    expect(String(putCall![0])).toBe('https://edge.example.com/api/file/abc123');
+    expect(putCall![1]?.method).toBe('POST');
+    expect(putCall![1]?.body).toBe(bytes);
+    expect((putCall![1]?.headers as Record<string, string>)['Content-Type']).toBe('application/octet-stream');
+  });
+
+  test('putBlob retries with an auth header after a 401 challenge', async ({ expect }) => {
+    const identity: EdgeIdentity = {
+      peerKey: 'peer-key',
+      identityDid: 'did:halo:test',
+      presentCredentials: async (): Promise<Presentation> => ({}),
+    };
+
+    const fetchMock = vi.fn(async (input: any, init?: RequestInit) => {
+      const url = String(input instanceof URL ? input : (input.url ?? input));
+      if (url.endsWith('/auth')) {
+        return new Response(null, { status: 200 });
+      }
+      const headers = init?.headers as Record<string, string> | undefined;
+      if (!headers?.Authorization) {
+        return new Response(null, {
+          status: 401,
+          headers: { 'WWW-Authenticate': 'VerifiablePresentation challenge=Y2hhbGxlbmdl' },
+        });
+      }
+      return new Response(null, { status: 200 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    client.setIdentity(identity);
+    await client.putBlob(Context.default(), 'abc123', new Uint8Array([1, 2, 3]));
+
+    const fileCalls = fetchMock.mock.calls.filter((call) => String(call[0]).includes('/api/file/abc123'));
+    expect(fileCalls.length).toBe(2);
+    expect((fileCalls[1][1]?.headers as Record<string, string>).Authorization).toMatch(/^VerifiablePresentation/);
+  });
+
+  test('getBlob returns bytes on success', async ({ expect }) => {
+    const fetchMock = vi.fn(async (input: any) => {
+      const url = String(input instanceof URL ? input : (input.url ?? input));
+      expect(url).toBe('https://edge.example.com/api/file/abc123');
+      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    const bytes = await client.getBlob(Context.default(), 'abc123');
+    expect(bytes).toEqual(new Uint8Array([1, 2, 3]));
+  });
+
+  test('getBlob returns undefined on 404', async ({ expect }) => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 404 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    const bytes = await client.getBlob(Context.default(), 'missing');
+    expect(bytes).toBeUndefined();
+  });
+
+  test('hasBlob sends a HEAD request and reflects 404 as false', async ({ expect }) => {
+    const fetchMock = vi.fn(async (_input: any, init?: RequestInit) => {
+      expect(init?.method).toBe('HEAD');
+      return new Response(null, { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    expect(await client.hasBlob(Context.default(), 'missing')).toBe(false);
+  });
+
+  test('deleteBlob sends a DELETE request', async ({ expect }) => {
+    const fetchMock = vi.fn(async (input: any, init?: RequestInit) => {
+      expect(String(input instanceof URL ? input : (input.url ?? input))).toBe(
+        'https://edge.example.com/api/file/abc123',
+      );
+      expect(init?.method).toBe('DELETE');
+      return new Response(null, { status: 200 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new EdgeHttpClient('https://edge.example.com');
+    await client.deleteBlob(Context.default(), 'abc123');
+    expect(fetchMock).toHaveBeenCalled();
+  });
+});

package/src/edge-http-client.ts

@@ -5,6 +5,7 @@
 import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
 import * as HttpClient from '@effect/platform/HttpClient';
 import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as EffectContext from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 
@@ -26,6 +27,8 @@ import {
   type ExportBundleRequest,
   type ExportBundleResponse,
   type FeedProtocol,
+  type GetAccessTokenRequest,
+  type GetAccessTokenResponseBody,
   type GetAgentStatusResponseBody,
   type GetNotarizationResponseBody,
   type GetPluginsResponseBody,
@@ -38,6 +41,7 @@ import {
   type PostNotarizationRequestBody,
   type RecoverIdentityRequest,
   type RecoverIdentityResponseBody,
+  type SerializedError,
   type UploadFunctionRequest,
   type UploadFunctionResponseBody,
 } from '@dxos/protocols';
@@ -81,8 +85,52 @@ export type GetCronTriggersResponse = {
   cronIds: string[];
 };
 
+/**
+ * Per-trigger runtime status reported by the EDGE dispatcher, keyed to the
+ * trigger's ECHO object id so a client can correlate it with the replicated
+ * `Trigger` object in its local database.
+ *
+ * TODO(edge): The backing endpoint (`GET /triggers/{spaceId}`, see
+ * {@link EdgeHttpClient.getSpaceTriggers}) is a proposal and is not yet
+ * implemented server-side.
+ */
+export type EdgeTriggerStatus = {
+  /** ECHO object id of the trigger. */
+  triggerId: ObjectId;
+  /** Whether the EDGE dispatcher currently has this trigger registered. */
+  registered: boolean;
+  kind: 'timer' | 'subscription' | 'email' | 'webhook' | 'feed' | 'direct';
+  /** Next scheduled cron execution (epoch ms). Set only for `timer` triggers. */
+  nextExecutionTimestamp?: number;
+  /** Cooldown expiry after a failure (epoch ms). */
+  cooldownUntilTimestamp?: number;
+  /** Outcome of the most recent invocation on the edge. */
+  lastResult?: {
+    status: 'success' | 'failure';
+    /** Completion time (epoch ms). */
+    timestamp: number;
+    error?: SerializedError;
+  };
+};
+
+/**
+ * Response of the proposed `GET /triggers/{spaceId}` endpoint: the full list of
+ * triggers registered on a space's EDGE dispatcher, with runtime status. Polled
+ * by the remote trigger monitor to surface edge trigger state.
+ */
+export type GetSpaceTriggersResponse = {
+  /** Whether the space's edge dispatcher is active. */
+  isActive: boolean;
+  triggers: EdgeTriggerStatus[];
+};
+
 export type EdgeHttpClientOptions = BaseHttpClientOptions;
 
+export class EdgeHttpClientService extends EffectContext.Tag('@dxos/edge-client/EdgeHttpClient')<
+  EdgeHttpClientService,
+  EdgeHttpClient
+>() {}
+
 /**
  * HTTP client for the edge worker API (spaces, queues, functions, agents, etc.).
  *
@@ -192,6 +240,18 @@ export class EdgeHttpClient extends BaseHttpClient {
     return this._call(ctx, new URL('/oauth/registration/complete', this.baseUrl), { ...args, body, method: 'POST' });
   }
 
+  /**
+   * Resolves the live access token behind a `MANAGED_ACCESS_TOKEN` placeholder. Authorized by the
+   * caller's presentation: EDGE serves it only to members of the owning space.
+   */
+  public async getAccessToken(
+    ctx: Context,
+    body: GetAccessTokenRequest,
+    args?: EdgeHttpCallArgs,
+  ): Promise<GetAccessTokenResponseBody> {
+    return this._call(ctx, new URL('/oauth/token', this.baseUrl), { ...args, body, method: 'POST' });
+  }
+
   //
   // Spaces
   //
@@ -208,10 +268,10 @@ export class EdgeHttpClient extends BaseHttpClient {
     ctx: Context,
     subspaceTag: string,
     spaceId: SpaceId,
-    query: FeedProtocol.QueueQuery,
+    query: FeedProtocol.FeedQuery,
     args?: EdgeHttpCallArgs,
   ): Promise<EdgeQueryQueueResponse> {
-    const queueId = query.queueIds?.[0];
+    const queueId = query.feedIds?.[0];
     invariant(queueId, 'queueId required');
     return this._call(
       ctx,
@@ -258,6 +318,72 @@ export class EdgeHttpClient extends BaseHttpClient {
     );
   }
 
+  //
+  // Blobs
+  //
+
+  /**
+   * Builds the URL for the blob stored under `key`. `key` is URL-encoded for defense in depth —
+   * callers pass a lowercase hex SHA-256 digest (extracted from an `ni:` URI by the edge backend).
+   */
+  public getBlobUrl(key: string): URL {
+    return new URL(`/api/file/${encodeURIComponent(key)}`, this.baseUrl);
+  }
+
+  /**
+   * Uploads bytes to the edge blob service, keyed by content hash. Pre-fetches `/auth` (`auth:
+   * true`) so large bodies aren't sent twice on an auth challenge.
+   */
+  public async putBlob(
+    ctx: Context,
+    key: string,
+    data: Uint8Array,
+    args?: EdgeHttpCallArgs & { contentType?: string },
+  ): Promise<void> {
+    const headers: Record<string, string> = {};
+    if (args?.contentType) {
+      headers['Content-Type'] = args.contentType;
+    }
+    await this._callRaw(ctx, this.getBlobUrl(key), {
+      retry: args?.retry,
+      auth: args?.auth ?? true,
+      method: 'POST',
+      // `Uint8Array` is generic over `ArrayBufferLike` (incl. `SharedArrayBuffer`) while DOM's
+      // `BodyInit` only covers `ArrayBuffer`-backed views — a gap between the DOM lib types and
+      // the TS standard lib, not fixable by typing `data` differently.
+      body: data as BodyInit,
+      headers,
+    });
+  }
+
+  /**
+   * Downloads bytes previously stored with {@link putBlob}. Returns `undefined` if `key` is not
+   * found.
+   */
+  public async getBlob(ctx: Context, key: string, args?: EdgeHttpCallArgs): Promise<Uint8Array | undefined> {
+    const response = await this._callRaw(ctx, this.getBlobUrl(key), { ...args, method: 'GET' });
+    if (response.status === 404) {
+      return undefined;
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  /**
+   * Checks whether bytes are stored under `key`, without downloading them.
+   */
+  public async hasBlob(ctx: Context, key: string, args?: EdgeHttpCallArgs): Promise<boolean> {
+    const response = await this._callRaw(ctx, this.getBlobUrl(key), { ...args, method: 'HEAD' });
+    return response.status !== 404;
+  }
+
+  /**
+   * Deletes bytes stored under `key`. Not called by any core `Blob.remove` path in v1 (deletion is
+   * deferred), provided for completeness.
+   */
+  public async deleteBlob(ctx: Context, key: string, args?: EdgeHttpCallArgs): Promise<void> {
+    await this._callRaw(ctx, this.getBlobUrl(key), { ...args, method: 'DELETE' });
+  }
+
   //
   // Functions
   //
@@ -366,6 +492,34 @@ export class EdgeHttpClient extends BaseHttpClient {
     });
   }
 
+  /**
+   * Cancels the current run of a cron trigger on the EDGE dispatcher — its in-flight execution and
+   * `runAgain` continuation chain. The trigger stays enabled, so its schedule keeps firing.
+   */
+  public async cancelTriggerRun(ctx: Context, spaceId: SpaceId, triggerId: ObjectId) {
+    return this._call(ctx, new URL(`/functions/${spaceId}/triggers/crons/${triggerId}/cancel`, this.baseUrl), {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Returns the full list of triggers registered on a space's EDGE dispatcher, with per-trigger
+   * runtime status. Polled by the remote trigger monitor to surface edge trigger state.
+   *
+   * TODO(edge): Proposed endpoint; not yet implemented server-side.
+   */
+  public async getSpaceTriggers(
+    ctx: Context,
+    spaceId: SpaceId,
+    args?: EdgeHttpCallArgs,
+  ): Promise<GetSpaceTriggersResponse> {
+    return this._call<GetSpaceTriggersResponse>(ctx, new URL(`/triggers/${spaceId}`, this.baseUrl), {
+      ...args,
+      method: 'GET',
+      auth: true,
+    });
+  }
+
   //
   // Query
   //