Add support for readOnly and bestEffort queries (#58)

* Add support for readOnly and bestEffort queries
* Make "readOnly" required if txnOpts present

Author: emhagman

lib/client.d.ts

@@ -1,15 +1,15 @@
 import * as grpc from "grpc";
 import * as messages from "../generated/api_pb";
 import { DgraphClientStub } from "./clientStub";
-import { Txn } from "./txn";
+import { Txn, TxnOptions } from "./txn";
 import * as types from "./types";
 export declare class DgraphClient {
     private readonly clients;
     private readonly linRead;
     private debugMode;
     constructor(...clients: DgraphClientStub[]);
     alter(op: messages.Operation, metadata?: grpc.Metadata | null, options?: grpc.CallOptions | null): Promise<types.Payload>;
-    newTxn(): Txn;
+    newTxn(txnOpts?: TxnOptions): Txn;
     setDebugMode(mode?: boolean): void;
     debug(msg: string): void;
     getLinRead(): messages.LinRead;

lib/client.js

@@ -71,8 +71,8 @@ var DgraphClient = (function () {
             });
         });
     };
-    DgraphClient.prototype.newTxn = function () {
-        return new txn_1.Txn(this);
+    DgraphClient.prototype.newTxn = function (txnOpts) {
+        return new txn_1.Txn(this, txnOpts);
     };
     DgraphClient.prototype.setDebugMode = function (mode) {
         if (mode === void 0) { mode = true; }

lib/errors.d.ts

@@ -1,3 +1,4 @@
 export declare const ERR_NO_CLIENTS: Error;
 export declare const ERR_FINISHED: Error;
 export declare const ERR_ABORTED: Error;
+export declare const ERR_BEST_EFFORT_REQUIRED_READ_ONLY: Error;

lib/errors.js

@@ -3,3 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERR_NO_CLIENTS = new Error("No clients provided in DgraphClient constructor");
 exports.ERR_FINISHED = new Error("Transaction has already been committed or discarded");
 exports.ERR_ABORTED = new Error("Transaction has been aborted. Please retry");
+exports.ERR_BEST_EFFORT_REQUIRED_READ_ONLY = new Error("Best effort only works for read-only queries");

lib/txn.d.ts

@@ -2,13 +2,19 @@ import * as grpc from "grpc";
 import * as messages from "../generated/api_pb";
 import { DgraphClient } from "./client";
 import * as types from "./types";
+export declare type TxnOptions = {
+    readOnly?: boolean;
+    bestEffort?: boolean;
+};
 export declare class Txn {
     private readonly dc;
     private readonly ctx;
     private finished;
     private mutated;
+    private readonly useReadOnly;
+    private readonly useBestEffort;
     private sequencingProp;
-    constructor(dc: DgraphClient);
+    constructor(dc: DgraphClient, txnOpts?: TxnOptions);
     sequencing(sequencing: messages.LinRead.SequencingMap[keyof messages.LinRead.SequencingMap]): void;
     query(q: string, metadata?: grpc.Metadata, options?: grpc.CallOptions): Promise<types.Response>;
     queryWithVars(q: string, vars?: {

lib/txn.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     return new (P || (P = Promise))(function (resolve, reject) {
         function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
@@ -40,13 +51,22 @@ var errors_1 = require("./errors");
 var types = require("./types");
 var util_1 = require("./util");
 var Txn = (function () {
-    function Txn(dc) {
+    function Txn(dc, txnOpts) {
         this.finished = false;
         this.mutated = false;
+        this.useReadOnly = false;
+        this.useBestEffort = false;
         this.dc = dc;
         this.ctx = new messages.TxnContext();
         this.ctx.setLinRead(this.dc.getLinRead());
         this.sequencingProp = messages.LinRead.Sequencing.CLIENT_SIDE;
+        var defaultedTxnOpts = __assign({ readOnly: false, bestEffort: false }, txnOpts);
+        this.useReadOnly = defaultedTxnOpts.readOnly;
+        this.useBestEffort = defaultedTxnOpts.bestEffort;
+        if (this.useBestEffort && !this.useReadOnly) {
+            this.dc.debug("Client attempted to query using best-effort without setting the transaction to read-only");
+            throw errors_1.ERR_BEST_EFFORT_REQUIRED_READ_ONLY;
+        }
     }
     Txn.prototype.sequencing = function (sequencing) {
         this.sequencingProp = sequencing;
@@ -67,6 +87,8 @@ var Txn = (function () {
                         req = new messages.Request();
                         req.setQuery(q);
                         req.setStartTs(this.ctx.getStartTs());
+                        req.setReadOnly(this.useReadOnly);
+                        req.setBestEffort(this.useBestEffort);
                         linRead = this.ctx.getLinRead();
                         linRead.setSequencing(this.sequencingProp);
                         req.setLinRead(linRead);

src/client.ts

@@ -4,7 +4,7 @@ import * as messages from "../generated/api_pb";
 
 import { DgraphClientStub } from "./clientStub";
 import { ERR_NO_CLIENTS } from "./errors";
-import { Txn } from "./txn";
+import { Txn, TxnOptions } from "./txn";
 import * as types from "./types";
 import { mergeLinReads, stringifyMessage } from "./util";
 
@@ -54,8 +54,8 @@ export class DgraphClient {
     /**
      * newTxn creates a new transaction.
      */
-    public newTxn(): Txn {
-        return new Txn(this);
+    public newTxn(txnOpts?: TxnOptions): Txn {
+        return new Txn(this, txnOpts);
     }
 
     /**

src/errors.ts

@@ -1,3 +1,4 @@
 export const ERR_NO_CLIENTS = new Error("No clients provided in DgraphClient constructor");
 export const ERR_FINISHED = new Error("Transaction has already been committed or discarded");
 export const ERR_ABORTED = new Error("Transaction has been aborted. Please retry");
+export const ERR_BEST_EFFORT_REQUIRED_READ_ONLY = new Error("Best effort only works for read-only queries");

src/txn.ts

@@ -3,7 +3,7 @@ import * as grpc from "grpc";
 import * as messages from "../generated/api_pb";
 
 import { DgraphClient } from "./client";
-import { ERR_ABORTED, ERR_FINISHED } from "./errors";
+import { ERR_ABORTED, ERR_BEST_EFFORT_REQUIRED_READ_ONLY, ERR_FINISHED } from "./errors";
 import * as types from "./types";
 import {
     isAbortedError,
@@ -12,6 +12,11 @@ import {
     stringifyMessage,
 } from "./util";
 
+export type TxnOptions = {
+    readOnly?: boolean;
+    bestEffort?: boolean;
+};
+
 /**
  * Txn is a single atomic transaction.
  *
@@ -31,13 +36,22 @@ export class Txn {
     private readonly ctx: messages.TxnContext;
     private finished: boolean = false;
     private mutated: boolean = false;
+    private readonly useReadOnly: boolean = false;
+    private readonly useBestEffort: boolean = false;
     private sequencingProp: messages.LinRead.SequencingMap[keyof messages.LinRead.SequencingMap];
 
-    constructor(dc: DgraphClient) {
+    constructor(dc: DgraphClient, txnOpts?: TxnOptions) {
         this.dc = dc;
         this.ctx = new messages.TxnContext();
         this.ctx.setLinRead(this.dc.getLinRead());
         this.sequencingProp = messages.LinRead.Sequencing.CLIENT_SIDE;
+        const defaultedTxnOpts = {readOnly: false, bestEffort: false, ...txnOpts};
+        this.useReadOnly = defaultedTxnOpts.readOnly;
+        this.useBestEffort = defaultedTxnOpts.bestEffort;
+        if (this.useBestEffort && !this.useReadOnly) {
+            this.dc.debug(`Client attempted to query using best-effort without setting the transaction to read-only`);
+            throw ERR_BEST_EFFORT_REQUIRED_READ_ONLY;
+        }
     }
 
     public sequencing(sequencing: messages.LinRead.SequencingMap[keyof messages.LinRead.SequencingMap]): void {
@@ -71,6 +85,8 @@ export class Txn {
         const req = new messages.Request();
         req.setQuery(q);
         req.setStartTs(this.ctx.getStartTs());
+        req.setReadOnly(this.useReadOnly);
+        req.setBestEffort(this.useBestEffort);
 
         const linRead = this.ctx.getLinRead();
         // tslint:disable-next-line no-unsafe-any

tests/txn.spec.ts

@@ -66,6 +66,31 @@ describe("txn", () => {
             const p = txn.query('{ me(func: eq(name, "Alice")) { name }}');
             await expect(p).rejects.toBe(dgraph.ERR_FINISHED);
         });
+
+        it("should succeed without increasing startTs (readOnly=true)", async () => {
+            const res = await client.newTxn().query('{ me(func: eq(name, "Alice")) { name }}');
+            const startTs = res.getTxn().getStartTs();
+            const res2 = await client.newTxn({ readOnly: true }).query('{ me(func: eq(name, "Alice")) { name }}');
+            const startTs2 = res2.getTxn().getStartTs();
+            expect(startTs).not.toBe(startTs2); // we expect these to be different, the first query increases startTs
+            const res3 = await client.newTxn({ readOnly: true }).query('{ me(func: eq(name, "Alice")) { name }}');
+            const startTs3 = res3.getTxn().getStartTs();
+            expect(startTs2).toBe(startTs3); // we expect these to be same, because readOnly doesn't increase startTs
+        });
+
+        it("should succeed without error (readOnly=true, bestEffort=true)", async () => {
+            const res = await client.newTxn().query('{ me(func: eq(name, "Alice")) { name }}');
+            const startTs = res.getTxn().getStartTs();
+            const res2 = await client.newTxn({ readOnly: true, bestEffort: true }).query('{ me(func: eq(name, "Alice")) { name }}');
+            const startTs2 = res2.getTxn().getStartTs();
+            expect(startTs2).toBeGreaterThanOrEqual(startTs);
+        });
+
+        it("should throw error (readOnly=false, bestEffort=true)", () => {
+            const test = () => client.newTxn({ bestEffort: true });
+            expect(test).toThrow(dgraph.ERR_BEST_EFFORT_REQUIRED_READ_ONLY);
+        });
+
     });
 
     describe("mutate", () => {