diff --git a/src/server/token/TokenStore.ts b/src/server/token/store/PersistentTokenStore.ts similarity index 96% rename from src/server/token/TokenStore.ts rename to src/server/token/store/PersistentTokenStore.ts index 23ff313..6f4d871 100644 --- a/src/server/token/TokenStore.ts +++ b/src/server/token/store/PersistentTokenStore.ts @@ -1,5 +1,5 @@ /** - * Token management + * Persistent token management * * Copyright (C) 2010-2019 R-T Specialty, LLC. * @@ -27,14 +27,15 @@ import { TokenStateAcceptable, TokenStateDeadable, TokenStateDoneable, -} from "./Token"; +} from "../Token"; -import { TokenDao, TokenData } from "./TokenDao"; -import { DocumentId } from "../../document/Document"; +import { TokenStore } from "./TokenStore"; +import { TokenDao, TokenData } from "../TokenDao"; +import { DocumentId } from "../../../document/Document"; /** - * Token storage + * Persistent token storage * * This store is used to create, read, and modify tokens. Its API is * designed to constrain state transitions at compile-time. @@ -86,7 +87,7 @@ import { DocumentId } from "../../document/Document"; * * For more information on tokens, see `Token`. */ -export class TokenStore +export class PersistentTokenStore implements TokenStore { /** * Initialize store diff --git a/src/server/token/store/TokenStore.ts b/src/server/token/store/TokenStore.ts new file mode 100644 index 0000000..3ef9f13 --- /dev/null +++ b/src/server/token/store/TokenStore.ts @@ -0,0 +1,120 @@ +/** + * Token management + * + * Copyright (C) 2010-2019 R-T Specialty, LLC. + * + * This file is part of the Liza Data Collection Framework. + * + * liza is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + */ + +import { + Token, + TokenId, + TokenState, + TokenStateAcceptable, + TokenStateDeadable, + TokenStateDoneable, +} from "../Token"; + + +/** + * Token storage + * + * This store is used to create, read, and modify tokens. Its API is + * designed to constrain state transitions at compile-time. + */ +export interface TokenStore +{ + /** + * Look up an existing token by id + * + * This looks up the given token id `token_id` for the document, + * constrained to this store's namespace and document id. + * + * The state of the returned token cannot be determined until runtime, + * so the caller is responsible for further constraining the type. + * + * @param token_id token id + * + * @return requested token, if it exists + */ + lookupToken( token_id: TokenId ): Promise>; + + + /** + * Create a new token for the given document within the store's + * namespace + * + * The returned token will always be `ACTIVE` and will always have + * `last_mistmatch` set. + */ + createToken(): Promise>; + + + /** + * Complete a token + * + * Completing a token places it into a `DONE` state. Only certain + * types of tokens can be completed (`TokenStateDoneable`). + * + * A token that in a `DONE` state means that processing has completed + * and is waiting acknowledgement from the system responsible for + * handling the response. + * + * @param src token to complete + * @param data optional response data + * + * @return token in `DONE` state + */ + completeToken( src: Token, data: string | null ): + Promise>; + + + /** + * Acknowledge a token as accepted + * + * Accepting a token places it into an `ACCEPTED` state. Only certain + * types of tokens can be accepted (`TokenStateAcceptable`). + * + * A token that in an `ACCEPTED` state means that a previously completed + * token has been acknowledged and all resources related to the + * processing of the token can be freed. + * + * @param src token to accept + * @param data optional accept reason + * + * @return token in `ACCEPTED` state + */ + acceptToken( src: Token, data: string | null ): + Promise>; + + + /** + * Kill a token + * + * Killing a token places it into a `DEAD` state. Only certain types of + * tokens can be killed (`TokenStateDeadable`). + * + * A token that in a `DEAD` state means that any processing related to + * that token should be aborted. + * + * @param src token to kill + * @param data optional kill reason + * + * @return token in `DEAD` state + */ + killToken( src: Token, data: string | null ): + Promise>; +} diff --git a/test/server/token/TokenStoreTest.ts b/test/server/token/store/PersistentTokenStoreTest.ts similarity index 97% rename from test/server/token/TokenStoreTest.ts rename to test/server/token/store/PersistentTokenStoreTest.ts index 9ed12a8..ff2409b 100644 --- a/test/server/token/TokenStoreTest.ts +++ b/test/server/token/store/PersistentTokenStoreTest.ts @@ -1,5 +1,5 @@ /** - * Tests token management + * Tests persistent token management * * Copyright (C) 2010-2019 R-T Specialty, LLC. * @@ -19,22 +19,25 @@ * along with this program. If not, see . */ -import { TokenStore as Sut } from "../../../src/server/token/TokenStore"; -import { TokenDao, TokenData } from "../../../src/server/token/TokenDao"; -import { DocumentId } from "../../../src/document/Document"; +import { + PersistentTokenStore as Sut +} from "../../../../src/server/token/store/PersistentTokenStore"; + +import { TokenDao, TokenData } from "../../../../src/server/token/TokenDao"; +import { DocumentId } from "../../../../src/document/Document"; import { Token, TokenId, TokenNamespace, TokenState, -} from "../../../src/server/token/Token"; +} from "../../../../src/server/token/Token"; import { expect, use as chai_use } from 'chai'; chai_use( require( 'chai-as-promised' ) ); -describe( 'TokenStore', () => +describe( 'PersistentTokenStore', () => { // required via the ctor, but this name is just used to denote that it's // not used for a particular test