feat: DeadlineService (#790)

fix: sendTimeStamp and receiveTimeStamp are not optional, repository validate them

Author: fboucquez

package-lock.json

@@ -27,10 +27,10 @@ export class NodeTime {
         /**
          * The request send timestamp
          */
-        public readonly sendTimeStamp?: UInt64,
+        public readonly sendTimeStamp: UInt64,
         /**
          * The request received timestamp
          */
-        public readonly receiveTimeStamp?: UInt64,
+        public readonly receiveTimeStamp: UInt64,
     ) {}
 }

src/model/node/NodeTime.ts

@@ -16,7 +16,8 @@
 
 import { ChronoUnit, Duration, Instant, LocalDateTime, ZoneId } from '@js-joda/core';
 import { UInt64 } from '../UInt64';
-
+export const defaultChronoUnit = ChronoUnit.HOURS;
+export const defaultDeadline = 2;
 /**
  * The deadline of the transaction. The deadline is given as the number of seconds elapsed since the creation of the nemesis block.
  * If a transaction does not get included in a block before the deadline is reached, it is deleted.
@@ -34,23 +35,34 @@ export class Deadline {
      * @param {ChronoUnit} chronoUnit the crhono unit. e.g ChronoUnit.HOURS
      * @returns {Deadline}
      */
-    public static create(epochAdjustment: number, deadline = 2, chronoUnit: ChronoUnit = ChronoUnit.HOURS): Deadline {
+    public static create(epochAdjustment: number, deadline = defaultDeadline, chronoUnit: ChronoUnit = defaultChronoUnit): Deadline {
         const deadlineDateTime = Instant.now().plus(deadline, chronoUnit);
 
         if (deadline <= 0) {
             throw new Error('deadline should be greater than 0');
         }
-        return new Deadline(deadlineDateTime.minusSeconds(Duration.ofSeconds(epochAdjustment).seconds()).toEpochMilli());
+        return Deadline.createFromAdjustedValue(deadlineDateTime.minusSeconds(epochAdjustment).toEpochMilli());
     }
 
     /**
-     * @internal
+     *
      * Create an empty Deadline object using min local datetime.
-     * This is method is an internal method to cope with undefined deadline for embedded transactions
+     * It can be used used for embedded or nemesis transactions
+     *
      * @returns {Deadline}
      */
     public static createEmtpy(): Deadline {
-        return new Deadline(0);
+        return Deadline.createFromAdjustedValue(0);
+    }
+
+    /**
+     *
+     * Create a Deadline where the adjusted values was externally calculated.
+     *
+     * @returns {Deadline}
+     */
+    public static createFromAdjustedValue(adjustedValue: number): Deadline {
+        return new Deadline(adjustedValue);
     }
 
     /**

src/model/transaction/Deadline.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2021 NEM
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ChronoUnit, Duration, Instant } from '@js-joda/core';
+import { RepositoryFactory } from '../infrastructure';
+import { Deadline, defaultChronoUnit, defaultDeadline } from '../model/transaction';
+
+/**
+ * A factory service that allows the client to generate Deadline objects based on different strategies.
+ *
+ * The main issue is that sometimes the local computer time is not in sync, the created deadlines may be too old or too in the future and rejected by the server.
+ */
+export class DeadlineService {
+    /**
+     * The difference in milliseconds between the server and the local time. It used to create "server" deadline without asking for the server time every time a new deadline is created.
+     */
+    private localTimeOffset: number;
+
+    /**
+     * Private constructor, use the create static method
+     *
+     * @param repositoryFactory the repository factory to call the rest servers.
+     * @param epochAdjustment the server epochAdjustment
+     * @param serverTime the latest known server time to calculate the remote and local time difference.
+     */
+    private constructor(
+        private readonly repositoryFactory: RepositoryFactory,
+        private readonly epochAdjustment: number,
+        serverTime: number,
+    ) {
+        this.localTimeOffset = Instant.now().minusSeconds(epochAdjustment).toEpochMilli() - serverTime;
+    }
+
+    /**
+     * It creates a deadline by querying the current time to the server each time. This is the most accurate but less efficient way.
+     *
+     * @param deadline the deadline value
+     * @param chronoUnit the unit of the value.
+     */
+    public async createDeadlineUsingServerTime(deadline = defaultDeadline, chronoUnit: ChronoUnit = defaultChronoUnit): Promise<Deadline> {
+        const serverTime = (await this.repositoryFactory.createNodeRepository().getNodeTime().toPromise()).receiveTimeStamp.compact();
+        return Deadline.createFromAdjustedValue(Duration.ofMillis(serverTime).plus(deadline, chronoUnit).toMillis());
+    }
+
+    /**
+     * It creates a deadline using the known difference between the local and server time.
+     *
+     * @param deadline the deadline value
+     * @param chronoUnit the unit of the value.
+     */
+    public createDeadlineUsingOffset(deadline = defaultDeadline, chronoUnit: ChronoUnit = defaultChronoUnit): Deadline {
+        return Deadline.createFromAdjustedValue(
+            Instant.now().plus(deadline, chronoUnit).minusMillis(this.localTimeOffset).minusSeconds(this.epochAdjustment).toEpochMilli(),
+        );
+    }
+
+    /**
+     * It creates a deadline using the local time. If the local system time is not in sync, the Deadline may be rejected by the server.
+     *
+     * @param deadline the deadline value
+     * @param chronoUnit the unit of the value.
+     */
+    public createDeadlineUsingLocalTime(deadline = defaultDeadline, chronoUnit: ChronoUnit = defaultChronoUnit): Deadline {
+        return Deadline.create(this.epochAdjustment, deadline, chronoUnit);
+    }
+
+    /**
+     * Factory method of this object.
+     *
+     * @param repositoryFactory the repository factory to call the rest servers.
+     */
+    public static async create(repositoryFactory: RepositoryFactory): Promise<DeadlineService> {
+        const epochAdjustment = await repositoryFactory.getEpochAdjustment().toPromise();
+        const serverTime = (await repositoryFactory.createNodeRepository().getNodeTime().toPromise()).receiveTimeStamp.compact();
+        return new DeadlineService(repositoryFactory, epochAdjustment, serverTime);
+    }
+}

src/service/DeadlineService.ts

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2018 NEM
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ChronoUnit, Instant, ZoneId } from '@js-joda/core';
+import { expect } from 'chai';
+import { of as observableOf } from 'rxjs';
+import { instance, mock, when } from 'ts-mockito';
+import { NodeRepository, RepositoryFactory } from '../../src/infrastructure';
+import { Deadline, UInt64 } from '../../src/model';
+import { NodeTime } from '../../src/model/node';
+import { DeadlineService } from '../../src/service/DeadlineService';
+
+describe('DeadlineService', () => {
+    const realNow = Instant.now;
+    const currentSystemMillis = Instant.parse('2021-05-31T10:20:21.154Z').toEpochMilli();
+    const localtimeError = 10 * 1000; // 10 seconds diff
+    const epochAdjustment = 1616694977;
+    const currentServerMillis = currentSystemMillis - epochAdjustment * 1000 - localtimeError;
+    before(() => {
+        Instant.now = () => Instant.ofEpochMilli(currentSystemMillis);
+    });
+
+    after(() => {
+        Instant.now = realNow;
+    });
+    const createService = () => {
+        const mockNodeRepository: NodeRepository = mock<NodeRepository>();
+        when(mockNodeRepository.getNodeTime()).thenReturn(
+            observableOf(new NodeTime(UInt64.fromUint(currentServerMillis), UInt64.fromUint(currentServerMillis))),
+        );
+        const mockRepoFactory = mock<RepositoryFactory>();
+        when(mockRepoFactory.getEpochAdjustment()).thenReturn(observableOf(epochAdjustment));
+        when(mockRepoFactory.createNodeRepository()).thenReturn(instance(mockNodeRepository));
+        const repositoryFactory = instance(mockRepoFactory);
+        return DeadlineService.create(repositoryFactory);
+    };
+
+    const printDeadline = (deadline: Deadline) => deadline.toLocalDateTimeGivenTimeZone(epochAdjustment, ZoneId.UTC).toString();
+
+    it('createDeadlines', async () => {
+        const service = await createService();
+        // createDeadlineUsingLocalTime is 10 seconds ahead
+        expect(printDeadline(service.createDeadlineUsingOffset())).eq('2021-05-31T12:20:11.154');
+        expect(printDeadline(await service.createDeadlineUsingServerTime())).eq('2021-05-31T12:20:11.154');
+        expect(printDeadline(service.createDeadlineUsingLocalTime())).eq('2021-05-31T12:20:21.154');
+
+        expect(printDeadline(service.createDeadlineUsingOffset(1))).eq('2021-05-31T11:20:11.154');
+        expect(printDeadline(await service.createDeadlineUsingServerTime(1))).eq('2021-05-31T11:20:11.154');
+        expect(printDeadline(service.createDeadlineUsingLocalTime(1))).eq('2021-05-31T11:20:21.154');
+
+        expect(printDeadline(service.createDeadlineUsingOffset(5, ChronoUnit.MINUTES))).eq('2021-05-31T10:25:11.154');
+        expect(printDeadline(await service.createDeadlineUsingServerTime(5, ChronoUnit.MINUTES))).eq('2021-05-31T10:25:11.154');
+        expect(printDeadline(service.createDeadlineUsingLocalTime(5, ChronoUnit.MINUTES))).eq('2021-05-31T10:25:21.154');
+    });
+});