@vida-global/core 2.5.0 → 3.0.1

package/test/search/openSearchClient.test.js

@@ -0,0 +1,514 @@
+const { BulkWriteError, UnsupportedOperationError } = require('../../lib/search/errors');
+const { OpenSearchClient } = require('../../lib/search/openSearchClient');
+const   TestHelpers        = require('@vida-global/test-helpers');
+const {
+    MOCK_ENDPOINT,
+    MOCK_INDEX,
+    MOCK_MAPPING,
+    buildHit,
+    buildOpenSearchClient,
+    buildSearchResponse,
+    buildUnsupportedError
+} = require('./helpers/searchClient');
+
+
+const randomString = () => TestHelpers.Faker.Text.randomString();
+
+
+describe('OpenSearchClient', () => {
+    let client;
+    let index;
+
+
+    beforeEach(() => {
+        client = buildOpenSearchClient();
+        index  = MOCK_INDEX;
+    });
+
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+
+    describe('#endpoint', () => {
+        it('is not implemented until a subclass declares it', () => {
+            class BareClient extends OpenSearchClient {}
+
+            expect(() => new BareClient().endpoint).toThrow('Not Implemented');
+        });
+    });
+
+
+    describe('index names', () => {
+        it('writes to the plain index when there is no suffix', () => {
+            expect(client.writeIndex).toBe(index);
+        });
+
+
+        it('writes to the suffixed index when there is a suffix', () => {
+            expect(buildOpenSearchClient({indexSuffix: '2026-10'}).writeIndex)
+                .toBe(`${index}-2026-10`);
+        });
+
+
+        it('reads across every suffixed index through the wildcard', () => {
+            expect(client.wildcardIndex).toBe(`${index}-*`);
+        });
+    });
+
+
+    describe('#_execute', () => {
+        it('searches the write index by default', async () => {
+            const body = {query: {}};
+
+            await client._execute(body, {});
+
+            expect(client.openSearchDouble.search).toHaveBeenCalledTimes(1);
+            expect(client.openSearchDouble.search).toHaveBeenCalledWith({index, body});
+        });
+
+
+        it('searches the wildcard index when asked to', async () => {
+            const body = {query: {}};
+
+            await client._execute(body, {indexWildcard: true});
+
+            expect(client.openSearchDouble.search)
+                .toHaveBeenCalledWith({index: `${index}-*`, body});
+        });
+    });
+
+
+    describe('response hooks', () => {
+        const response = buildSearchResponse([buildHit('a', {name: 'first'}, 9.5)], 57);
+
+
+        it('reads the hit container off the response', () => {
+            expect(client._hitsFromResponse(response)).toBe(response.body.hits);
+        });
+
+
+        it('reads the exact total off the response', () => {
+            expect(client._totalFromResponse(response)).toBe(57);
+        });
+
+
+        it('reports zero when the response carries no total', () => {
+            expect(client._totalFromResponse({body: {hits: {hits: []}}})).toBe(0);
+        });
+
+
+        it.each([
+            ['_idFromHit',       'a'],
+            ['_scoreFromHit',    9.5],
+            ['_documentFromHit', {name: 'first'}],
+        ])('%s reads its field off the hit', (hook, expected) => {
+            expect(client[hook](response.body.hits.hits[0])).toEqual(expected);
+        });
+
+
+        it('shapes a whole response into the standard envelope', () => {
+            expect(client._processResponse(response)).toEqual({
+                total:   57,
+                results: [{id: 'a', score: 9.5, document: {name: 'first'}}]
+            });
+        });
+    });
+
+
+    describe('#_serializeConditions', () => {
+        const serialize = (build) => client._serializeConditions(build(client.query()).conditions);
+
+
+        it('always asks OpenSearch for an exact total', () => {
+            expect(serialize(query => query).track_total_hits).toBe(true);
+        });
+
+
+        it('puts and conditions into must and not conditions into must_not', () => {
+            const body = serialize(query => query
+                .equals('status', 'success')
+                .not({operator: 'exists', field: 'deletedAt'}));
+
+            expect(body.query).toEqual({
+                bool: {
+                    must:     [{term: {status: {value: 'success'}}}],
+                    must_not: [{exists: {field: 'deletedAt'}}]
+                }
+            });
+        });
+
+
+        it('wraps or conditions in a should group that still filters', () => {
+            const body = serialize(query => query
+                .equals('status', 'success')
+                .or({operator: 'equals', field: 'from', value: 'x'},
+                    {operator: 'equals', field: 'to',   value: 'x'}));
+
+            expect(body.query.bool.must).toEqual([
+                {term: {status: {value: 'success'}}},
+                {
+                    bool: {
+                        should: [
+                            {term: {from: {value: 'x'}}},
+                            {term: {to:   {value: 'x'}}}
+                        ],
+                        minimum_should_match: 1
+                    }
+                }
+            ]);
+        });
+
+
+        it('drops the bool wrapper around a lone clause', () => {
+            expect(serialize(query => query.exists('summary')).query)
+                .toEqual({exists: {field: 'summary'}});
+        });
+
+
+        it('keeps the bool wrapper once there is more than one clause', () => {
+            const body = serialize(query => query.exists('summary').exists('message'));
+
+            expect(body.query.bool.must).toHaveLength(2);
+        });
+
+
+        it('matches everything when no condition was added', () => {
+            expect(serialize(query => query).query).toEqual({bool: {must: [], must_not: []}});
+        });
+
+
+        it('serializes a nested sub-query tree', () => {
+            const subQuery = client.query().matches('addresses.address', 'home');
+            const body     = serialize(query => query.nested('addresses', subQuery));
+
+            expect(body.query).toEqual({
+                nested: {
+                    path:  'addresses',
+                    query: {match: {'addresses.address': {query: 'home', fuzziness: 'AUTO'}}}
+                }
+            });
+        });
+
+
+        it.each([
+            ['equals',  query => query.equals('status', 'ok'),        {term: {status: {value: 'ok'}}}],
+            ['in',      query => query.in('roomId', ['a', 'b']),      {terms: {roomId: ['a', 'b']}}],
+            ['range',   query => query.range('ts', {gte: 1, lte: 9}), {range: {ts: {gte: 1, lte: 9}}}],
+            ['exists',  query => query.exists('summary'),             {exists: {field: 'summary'}}],
+            ['missing', query => query.missing('summary'),            {bool: {must_not: {exists: {field: 'summary'}}}}],
+            ['phrase',  query => query.phrase('message', 'hi'),       {match_phrase: {message: {query: 'hi'}}}],
+        ])('serializes a %s leaf', (_operator, build, expected) => {
+            expect(serialize(build).query).toEqual(expected);
+        });
+
+
+        it('serializes a matches leaf with its fuzziness', () => {
+            const body = serialize(query => query.matches('message', 'hi', {fuzziness: 2}));
+
+            expect(body.query).toEqual({match: {message: {query: 'hi', fuzziness: 2}}});
+        });
+
+
+        it('serializes a fullText leaf by gluing each boost onto its field name', () => {
+            const body = serialize(query => query.fullText('hi', {
+                fields: ['message', 'summary'],
+                boost:  {summary: 5}
+            }));
+
+            expect(body.query).toEqual({
+                query_string: {query: 'hi', fields: ['message^1', 'summary^5']}
+            });
+        });
+
+
+        it('wraps a fullText leaf in asterisks only when the caller asks', () => {
+            const body = serialize(query => query.fullText('hi', {
+                fields:   ['message'],
+                wildcard: true
+            }));
+
+            expect(body.query).toEqual({
+                query_string: {query: '*hi*', fields: ['message^1']}
+            });
+        });
+
+
+        it('maps paging, score floor and sort onto the request body', () => {
+            const body = serialize(query => query
+                .limit(50)
+                .offset(100)
+                .minScore(5)
+                .sort('timestamp', 'desc')
+                .sort('score', 'asc'));
+
+            expect(body.size).toBe(50);
+            expect(body.from).toBe(100);
+            expect(body.min_score).toBe(5);
+            expect(body.sort).toEqual([
+                {timestamp: {order: 'desc'}},
+                {score:     {order: 'asc'}}
+            ]);
+        });
+
+
+        it('leaves paging keys out when they were never set', () => {
+            const body = serialize(query => query.equals('status', 'ok'));
+
+            expect(body).not.toHaveProperty('size');
+            expect(body).not.toHaveProperty('from');
+            expect(body).not.toHaveProperty('min_score');
+            expect(body).not.toHaveProperty('sort');
+        });
+
+
+        it('keeps an explicit zero offset', () => {
+            expect(serialize(query => query.offset(0)).from).toBe(0);
+        });
+    });
+
+
+    describe('#_upsert', () => {
+        it('updates the document in place and creates it when it is new', async () => {
+            const id       = randomString();
+            const document = {name: randomString()};
+
+            await client._upsert(id, document);
+
+            expect(client.openSearchDouble.update).toHaveBeenCalledTimes(1);
+            expect(client.openSearchDouble.update).toHaveBeenCalledWith({
+                id,
+                index,
+                body: {doc: document, doc_as_upsert: true}
+            });
+        });
+
+
+        it('turns a collection refusal into UnsupportedOperationError', async () => {
+            const refusal = buildUnsupportedError();
+            client.openSearchDouble.update.mockRejectedValue(refusal);
+
+            await expect(client._upsert('a', {})).rejects.toThrow(UnsupportedOperationError);
+            await expect(client._upsert('a', {})).rejects.toThrow(/upsert is not supported/);
+        });
+
+
+        it('keeps the refusal as the cause', async () => {
+            const refusal = buildUnsupportedError();
+            client.openSearchDouble.update.mockRejectedValue(refusal);
+
+            await client._upsert('a', {}).catch((error) => {
+                expect(error.cause).toBe(refusal);
+            });
+        });
+
+
+        it('lets every other error through untouched', async () => {
+            const failure = Object.assign(new Error('gateway timeout'), {statusCode: 504});
+            client.openSearchDouble.update.mockRejectedValue(failure);
+
+            await expect(client._upsert('a', {})).rejects.toBe(failure);
+        });
+    });
+
+
+    describe('#_isUnsupportedOperation', () => {
+        it.each([
+            [400, 'Document ID is not supported for this collection', true],
+            [400, 'mapper_parsing_exception',                         false],
+            [404, 'index is not supported',                           false],
+            [503, 'service unavailable',                              false],
+        ])('reads a %i "%s" as %s', (statusCode, message, expected) => {
+            const error = Object.assign(new Error(message), {statusCode});
+
+            expect(client._isUnsupportedOperation(error)).toBe(expected);
+        });
+
+
+        it('reads the status out of the error meta when it is not on the error', () => {
+            const error = Object.assign(new Error('not supported'), {meta: {statusCode: 400}});
+
+            expect(client._isUnsupportedOperation(error)).toBe(true);
+        });
+    });
+
+
+    describe('#_append', () => {
+        it('writes the document without an id', async () => {
+            const document = {name: randomString()};
+
+            await client._append(document);
+
+            expect(client.openSearchDouble.index).toHaveBeenCalledTimes(1);
+            expect(client.openSearchDouble.index).toHaveBeenCalledWith({index, body: document});
+        });
+    });
+
+
+    describe('#_delete', () => {
+        it('deletes the document by id', async () => {
+            const id = randomString();
+
+            await client._delete(id);
+
+            expect(client.openSearchDouble.delete).toHaveBeenCalledTimes(1);
+            expect(client.openSearchDouble.delete).toHaveBeenCalledWith({id, index});
+        });
+    });
+
+
+    describe('#_bulkUpsert', () => {
+        const documents = [
+            {id: 'a', document: {name: 'first'}},
+            {id: 'b', document: {name: 'second'}}
+        ];
+
+
+        it('sends one action pair per document', async () => {
+            client.openSearchDouble.bulk.mockResolvedValue({body: {errors: false}});
+
+            await client._bulkUpsert(documents);
+
+            expect(client.openSearchDouble.bulk).toHaveBeenCalledWith({
+                body: [
+                    {update: {_id: 'a', _index: index}},
+                    {doc: {name: 'first'},  doc_as_upsert: true},
+                    {update: {_id: 'b', _index: index}},
+                    {doc: {name: 'second'}, doc_as_upsert: true}
+                ]
+            });
+        });
+
+
+        it('throws with every failed id when the response reports errors', async () => {
+            client.openSearchDouble.bulk.mockResolvedValue({
+                body: {
+                    errors: true,
+                    items: [
+                        {update: {_id: 'a'}},
+                        {update: {_id: 'b', error: {reason: 'mapper_parsing_exception'}}}
+                    ]
+                }
+            });
+
+            await expect(client._bulkUpsert(documents)).rejects.toThrow(BulkWriteError);
+
+            await client._bulkUpsert(documents).catch((error) => {
+                expect(error.failures).toEqual([{id: 'b', reason: 'mapper_parsing_exception'}]);
+            });
+        });
+
+
+        it('turns a collection refusal into UnsupportedOperationError', async () => {
+            client.openSearchDouble.bulk.mockRejectedValue(buildUnsupportedError());
+
+            await expect(client._bulkUpsert(documents))
+                .rejects.toThrow(/bulkUpsert is not supported/);
+        });
+    });
+
+
+    describe('#syncIndex', () => {
+        it('creates the index and then pushes the mapping when it is missing', async () => {
+            client.openSearchDouble.indices.exists.mockResolvedValue({body: false});
+
+            await client.syncIndex();
+
+            expect(client.openSearchDouble.indices.create).toHaveBeenCalledWith({index});
+            expect(client.openSearchDouble.indices.putMapping)
+                .toHaveBeenCalledWith({index, body: MOCK_MAPPING});
+        });
+
+
+        it('only pushes the mapping when the index already exists', async () => {
+            client.openSearchDouble.indices.exists.mockResolvedValue({body: true});
+
+            await client.syncIndex();
+
+            expect(client.openSearchDouble.indices.create).not.toHaveBeenCalled();
+            expect(client.openSearchDouble.indices.putMapping).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#shouldRetry', () => {
+        const errorWithStatus = (statusCode) => Object.assign(new Error('boom'), {statusCode});
+
+
+        it('never retries when numRetries is zero', () => {
+            expect(client.shouldRetry(1, errorWithStatus(503))).toBe(false);
+        });
+
+
+        it.each([
+            [500, true],
+            [503, true],
+            [599, true],
+            [404, false],
+            [429, false],
+        ])('retries a %i response: %s', (statusCode, expected) => {
+            const retryingClient = buildOpenSearchClient({numRetries: 3});
+
+            expect(retryingClient.shouldRetry(1, errorWithStatus(statusCode))).toBe(expected);
+        });
+
+
+        it('reads the status out of the error meta when it is not on the error', () => {
+            const retryingClient = buildOpenSearchClient({numRetries: 3});
+            const error          = Object.assign(new Error('boom'), {meta: {statusCode: 502}});
+
+            expect(retryingClient.shouldRetry(1, error)).toBe(true);
+        });
+
+
+        it('stops once the attempts are used up', () => {
+            const retryingClient = buildOpenSearchClient({numRetries: 1});
+
+            expect(retryingClient.shouldRetry(2, errorWithStatus(503))).toBe(false);
+        });
+    });
+
+
+    describe('client configuration', () => {
+        it('builds the client once and reuses it', async () => {
+            await client._delete('a');
+            await client._delete('b');
+
+            expect(client.clientClassDouble).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('points the client at the endpoint and spreads in the signer', async () => {
+            await client._delete('a');
+
+            expect(client.clientClassDouble).toHaveBeenCalledWith({
+                Connection: 'signed-connection',
+                node:       MOCK_ENDPOINT
+            });
+        });
+
+
+        it('signs for the serverless collection service', async () => {
+            await client._delete('a');
+
+            expect(client.signerDouble).toHaveBeenCalledWith(expect.objectContaining({
+                service: 'aoss'
+            }));
+        });
+
+
+        it('resolves credentials from the environment when the signer asks', async () => {
+            process.env.OPENSEARCH_AWS_KEY    = 'key';
+            process.env.OPENSEARCH_AWS_SECRET = 'secret';
+
+            await expect(client.getCredentials()).resolves.toEqual({
+                accessKeyId:     'key',
+                secretAccessKey: 'secret'
+            });
+
+            delete process.env.OPENSEARCH_AWS_KEY;
+            delete process.env.OPENSEARCH_AWS_SECRET;
+        });
+    });
+});