Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .agents/docs/architecture/auth-and-permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ route.
`ADMIN_ONLY` guard; and `InstrumentsService.findBundleById` called without a `currentUser`, which the
API's gateway module does to resolve an assignment's bundle. That parameter is optional for this
reason, so a new call site that omits it compiles and reads every group's instruments.
`StartSessionService` rolls back unscoped: when the record of a session instrument fails to save,
it deletes the session it just created and, if `SubjectsService.exists` (a boolean, unscoped
because a scoped lookup would miss a subject in another group) found no subject beforehand, the
subject too. `SessionsService.createMany` rolls back the same way.

## Layer 2: row scoping

Expand Down
2 changes: 2 additions & 0 deletions apps/api/prisma/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,8 @@ type GroupSettings {
idValidationRegexErrorMessage LocalizedString?
subjectIdDisplayLength Int?
minimumAge Int?
// A form instrument that must be completed to start a session in the group, if any.
sessionInstrumentId String?
}

// Mirrors $LocalizedString in @opendatacapture/schemas/core; each field is optional so
Expand Down
72 changes: 71 additions & 1 deletion apps/api/src/groups/__tests__/groups.service.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import { beforeEach, describe, expect, it } from 'vitest';

import { AuditLogger } from '@/audit/audit.logger';
import { createAppAbility } from '@/auth/ability.utils';
import { InstrumentsService } from '@/instruments/instruments.service';

import { GroupsService } from '../groups.service';

Expand All @@ -30,20 +31,23 @@ describe('GroupsService', () => {
let groupsService: GroupsService;
let groupModel: MockedInstance<Model<'Group'>>;
let instrumentModel: MockedInstance<Model<'Instrument'>>;
let instrumentsService: MockedInstance<InstrumentsService>;

beforeEach(async () => {
const moduleRef = await Test.createTestingModule({
providers: [
GroupsService,
MockFactory.createForModelToken(getModelToken('Group')),
MockFactory.createForModelToken(getModelToken('Instrument')),
MockFactory.createForService(AuditLogger)
MockFactory.createForService(AuditLogger),
MockFactory.createForService(InstrumentsService)
]
}).compile();
auditLogger = moduleRef.get(AuditLogger);
groupModel = moduleRef.get(getModelToken('Group'));
instrumentModel = moduleRef.get(getModelToken('Instrument'));
groupsService = moduleRef.get(GroupsService);
instrumentsService = moduleRef.get(InstrumentsService);
instrumentModel.findMany.mockResolvedValue([]);
});

Expand Down Expand Up @@ -335,6 +339,72 @@ describe('GroupsService', () => {
});
});

describe('updateById with a session instrument', () => {
const groupRequiring = (sessionInstrumentId: null | string) => ({
accessibleInstrumentIds: ['form-1', 'form-2'],
name: 'Test Group',
settings: { sessionInstrumentId }
});

const accessibleInstruments = (...ids: string[]) => {
instrumentModel.findMany.mockResolvedValueOnce(ids.map((id) => ({ id })));
};

it("should refuse an update dropping the session instrument from the group's instruments, even one not naming the setting", async () => {
groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1'));
accessibleInstruments('form-2');
await expect(groupsService.updateById('123', { accessibleInstrumentIds: ['form-2'] })).rejects.toThrow(
/before removing instrument 'form-1'/
);
expect(groupModel.update).not.toHaveBeenCalled();
});

it('should refuse a session instrument the group cannot access, saying so rather than asking to remove it', async () => {
groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null));
const update = groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-3' } });
await expect(update).rejects.toBeInstanceOf(BadRequestException);
await expect(update).rejects.toThrow(/instrument 'form-3' is not$/);
expect(groupModel.update).not.toHaveBeenCalled();
});

it('should refuse a session instrument that is not a form, since only a form is rendered when a session starts', async () => {
groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null));
instrumentsService.findById.mockResolvedValueOnce({ kind: 'INTERACTIVE' });
await expect(
groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } })
).rejects.toBeInstanceOf(BadRequestException);
expect(groupModel.update).not.toHaveBeenCalled();
});

it("should look the new session instrument up within the caller's ability and the group", async () => {
const ability = createAppAbility([{ action: 'manage', subject: 'all' }]);
groupModel.findFirst.mockResolvedValueOnce(groupRequiring(null));
instrumentsService.findById.mockResolvedValueOnce({ kind: 'FORM' });
await groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } }, { ability });
expect(instrumentsService.findById).toHaveBeenCalledWith('form-1', { ability }, ['123']);
expect(groupModel.update.mock.lastCall?.[0]).toMatchObject({
data: { settings: { sessionInstrumentId: 'form-1' } }
});
});

it('should accept dropping the session instrument from the group once the setting is cleared in the same update', async () => {
groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1'));
accessibleInstruments('form-2');
await groupsService.updateById('123', {
accessibleInstrumentIds: ['form-2'],
settings: { sessionInstrumentId: null }
});
expect(groupModel.update.mock.lastCall?.[0]).toMatchObject({ data: { settings: { sessionInstrumentId: null } } });
});

it('should not look the session instrument up again when the update leaves it as it was', async () => {
groupModel.findFirst.mockResolvedValueOnce(groupRequiring('form-1'));
await groupsService.updateById('123', { settings: { sessionInstrumentId: 'form-1' } });
expect(instrumentsService.findById).not.toHaveBeenCalled();
expect(groupModel.update).toHaveBeenCalled();
});
});

describe('findAll', () => {
it('should return the array returned by the group model', async () => {
groupModel.findMany.mockResolvedValueOnce([{ name: 'Test Group' }]);
Expand Down
3 changes: 3 additions & 0 deletions apps/api/src/groups/groups.module.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
import { Module } from '@nestjs/common';

import { InstrumentsModule } from '@/instruments/instruments.module';

import { GroupsController } from './groups.controller';
import { GroupsService } from './groups.service';

@Module({
controllers: [GroupsController],
exports: [GroupsService],
imports: [InstrumentsModule],
providers: [GroupsService]
})
export class GroupsModule {}
52 changes: 51 additions & 1 deletion apps/api/src/groups/groups.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,15 @@ import { PrismaClientKnownRequestError } from '@prisma/client/runtime/library';
import { AuditLogger } from '@/audit/audit.logger';
import { accessibleQuery } from '@/auth/ability.utils';
import type { EntityOperationOptions } from '@/core/types';
import { InstrumentsService } from '@/instruments/instruments.service';

@Injectable()
export class GroupsService {
constructor(
@InjectModel('Group') private readonly groupModel: Model<'Group'>,
@InjectModel('Instrument') private readonly instrumentModel: Model<'Instrument'>,
private readonly auditLogger: AuditLogger
private readonly auditLogger: AuditLogger,
private readonly instrumentsService: InstrumentsService
) {}

async archiveById(id: string, currentUser: RequestUser) {
Expand Down Expand Up @@ -124,6 +126,15 @@ export class GroupsService {
});
validInstrumentIds = existingInstruments.map(({ id }) => id);
}
await this.validateSessionInstrument(
{
accessibleInstrumentIds: validInstrumentIds ?? group.accessibleInstrumentIds,
groupId: id,
sessionInstrumentId: settings?.sessionInstrumentId,
storedSessionInstrumentId: group.settings.sessionInstrumentId
},
{ ability }
);

try {
return await this.groupModel.update({
Expand Down Expand Up @@ -204,4 +215,43 @@ export class GroupsService {
throw new BadRequestException(`No email template with id '${nextActiveId}' exists in this group`);
}
}

/**
* Every update is checked, not only one naming the session instrument: removing the instrument from
* the group's accessible list would otherwise leave every Start Session in the group requiring a
* form no one in it can open.
*/
private async validateSessionInstrument(
{
accessibleInstrumentIds,
groupId,
sessionInstrumentId,
storedSessionInstrumentId
}: {
accessibleInstrumentIds: string[];
groupId: string;
sessionInstrumentId: null | string | undefined;
storedSessionInstrumentId: null | string | undefined;
},
options: EntityOperationOptions
): Promise<void> {
// `undefined` leaves the stored value alone; `null` removes it.
const nextSessionInstrumentId = sessionInstrumentId === undefined ? storedSessionInstrumentId : sessionInstrumentId;
if (!nextSessionInstrumentId) {
return;
}
if (!accessibleInstrumentIds.includes(nextSessionInstrumentId)) {
throw new BadRequestException(
nextSessionInstrumentId === storedSessionInstrumentId
? `The group's Session Instrument must be one of its accessible instruments: set the Session Instrument to another form, or to none, before removing instrument '${nextSessionInstrumentId}'`
: `The group's Session Instrument must be one of its accessible instruments, and instrument '${nextSessionInstrumentId}' is not`
);
}
if (nextSessionInstrumentId !== storedSessionInstrumentId) {
const instrument = await this.instrumentsService.findById(nextSessionInstrumentId, options, [groupId]);
if (instrument.kind !== 'FORM') {
throw new BadRequestException(`The group's Session Instrument must be a form, not '${instrument.kind}'`);
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -971,6 +971,28 @@ describe('InstrumentRecordsService', () => {
expect(projectStage.$project.session.user.username).toBe('$sessionUser.username');
});

// `$dateToString` without a format gives a full ISO timestamp, so the time of collection survives
// and two records collected on one day stay distinguishable.
it('should export the record collection date as the timestamp, not the insertion date', async () => {
instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]);

await instrumentRecordsService.exportRecords({}, { ability: createAppAbility([]) });

const [{ pipeline }] = instrumentRecordModel.aggregateRaw.mock.lastCall as [{ pipeline: any[] }];
const projectStage = pipeline.find((stage) => stage.$project);
expect(projectStage.$project.date).toStrictEqual({ $dateToString: { date: '$date' } });
});

it('should export the session date with its time of day, so a session started at a known time keeps it', async () => {
instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]);

await instrumentRecordsService.exportRecords({}, { ability: createAppAbility([]) });

const [{ pipeline }] = instrumentRecordModel.aggregateRaw.mock.lastCall as [{ pipeline: any[] }];
const projectStage = pipeline.find((stage) => stage.$project);
expect(projectStage.$project.session.date).toStrictEqual({ $dateToString: { date: '$session.date' } });
});

it('should match only the requested group in the aggregation, so a scoped export reads no other group', async () => {
instrumentRecordModel.aggregateRaw.mockResolvedValueOnce([]);

Expand Down
50 changes: 26 additions & 24 deletions apps/api/src/instrument-records/instrument-records.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import {
UnprocessableEntityException
} from '@nestjs/common';
import { translateInstrument } from '@opendatacapture/instrument-utils';
import type { Json, ScalarInstrument } from '@opendatacapture/runtime-core';
import type { FormInstrument, InstrumentValidationSchema, Json, ScalarInstrument } from '@opendatacapture/runtime-core';
import type {
CreateInstrumentRecordData,
InstrumentRecord,
Expand Down Expand Up @@ -141,15 +141,7 @@ export class InstrumentRecordsService {
await this.subjectsService.findById(subjectId);
await this.sessionsService.findById(sessionId);

const parseResult = instrument.validationSchema.safeParse(this.parseJson(rawData));
if (!parseResult.success) {
throw new UnprocessableEntityException({
error: 'Unprocessable Entity',
issues: parseResult.error.issues,
message: `Data received for record does not pass validation schema of instrument '${instrument.id}'`,
statusCode: 422
});
}
const data = this.parseData(instrument, rawData);

return this.instrumentRecordModel.create({
data: {
Expand All @@ -159,9 +151,9 @@ export class InstrumentRecordsService {
}
: undefined,
computedMeasures: instrument.measures
? this.instrumentMeasuresService.computeMeasures(instrument.measures, parseResult.data)
? this.instrumentMeasuresService.computeMeasures(instrument.measures, data)
: null,
data: this.serializeData(parseResult.data),
data: this.serializeData(data),
date,
group: groupId
? {
Expand Down Expand Up @@ -410,6 +402,26 @@ export class InstrumentRecordsService {
return results;
}

/** Throws exactly as `create` does for data the instrument's schema rejects. */
parseData(
instrument: {
id: string;
validationSchema: InstrumentValidationSchema<FormInstrument.Data> | InstrumentValidationSchema<Json>;
},
rawData: unknown
) {
const parseResult = instrument.validationSchema.safeParse(this.parseJson(rawData));
if (!parseResult.success) {
throw new UnprocessableEntityException({
error: 'Unprocessable Entity',
issues: parseResult.error.issues,
message: `Data received for record does not pass validation schema of instrument '${instrument.id}'`,
statusCode: 422
});
}
return parseResult.data;
}

/**
* Per-instrument collection statistics for the instrument hub's listing.
*
Expand Down Expand Up @@ -649,12 +661,7 @@ export class InstrumentRecordsService {
{
$project: {
computedMeasures: 1,
date: {
$dateToString: {
date: '$createdAt',
format: '%Y-%m-%d'
}
},
date: { $dateToString: { date: '$date' } },
// `$ifNull` for the same reason as in `summarizeRecords`: `$toString` of a missing field is
// itself missing, so a record belonging to no group would drop `groupId` from the row
// entirely and arrive as undefined behind a type that says it is a string.
Expand All @@ -665,12 +672,7 @@ export class InstrumentRecordsService {
instrumentId: 1,
seriesInstrumentId: { $ifNull: ['$seriesInstrumentId', null] },
session: {
date: {
$dateToString: {
date: '$session.date',
format: '%Y-%m-%d'
}
},
date: { $dateToString: { date: '$session.date' } },
id: {
$toString: '$session._id'
},
Expand Down
32 changes: 32 additions & 0 deletions apps/api/src/instruments/__tests__/instruments.service.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -728,6 +728,38 @@ describe('InstrumentsService', () => {
where: { accessibleInstrumentIds: { has: 'hash:REACTION_TIME-1' } }
});
});

it('should require a new edition of a form at the start of a session wherever the previous edition was required', async () => {
virtualizationService.eval.mockReturnValue(okAsync(formInstance('INTAKE', 2)));
instrumentModel.exists.mockResolvedValue(false);

await instrumentsService.create({ bundle: '__BUNDLE__' });

expect(groupModel.updateMany).toHaveBeenCalledWith({
data: { settings: { update: { sessionInstrumentId: 'hash:INTAKE-2' } } },
where: { settings: { is: { sessionInstrumentId: 'hash:INTAKE-1' } } }
});
});

it('should leave every group on the previous edition when the new one fails to save, so none requires a missing form', async () => {
virtualizationService.eval.mockReturnValue(okAsync(formInstance('INTAKE', 2)));
instrumentModel.exists.mockResolvedValue(false);
instrumentModel.create.mockRejectedValueOnce(new Error('connection reset'));

await expect(instrumentsService.create({ bundle: '__BUNDLE__' })).rejects.toThrowError('connection reset');
expect(groupModel.updateMany).not.toHaveBeenCalled();
});

it('should leave a session instrument on its edition when the new edition is not a form, since only a form can be required', async () => {
virtualizationService.eval.mockReturnValue(
okAsync({ ...interactiveInstrument, internal: { edition: 2, name: 'REACTION_TIME' } })
);
instrumentModel.exists.mockResolvedValue(false);

await instrumentsService.create({ bundle: '__BUNDLE__' });

expect(groupModel.updateMany).toHaveBeenCalledTimes(1);
});
});

describe('generateSeriesInstrumentId', () => {
Expand Down
Loading