Merge pull request #115 from wri/release/blazing-beryl

[RELEASE] Blazing Beryl

Author: roguenet

.github/workflows/deploy-service.yml

@@ -82,11 +82,12 @@ jobs:
           docker build -t terramatch-microservices-base:nx-base .
           SERVICE_IMAGE=$ECR_REGISTRY/$ECR_REPOSITORY:${{ env.IMAGE_TAG }}
           docker build \
+            --build-arg SERVICE=${{ inputs.service }} \
             --build-arg NODE_ENV=production \
             --build-arg DEPLOY_ENV=${{ inputs.env }} \
             --build-arg SENTRY_DSN="${{ secrets.SENTRY_DSN }}" \
             --build-arg BUILD_FLAG='--prod --verbose --no-cloud' \
-            -f apps/${{ inputs.service }}/Dockerfile \
+            -f service.Dockerfile \
             -t $SERVICE_IMAGE .
           docker push $SERVICE_IMAGE
           echo "image=$SERVICE_IMAGE"

.github/workflows/pull-request.yml

@@ -34,7 +34,7 @@ jobs:
           node-version: 20
           cache: "npm"
 
-      - run: npm ci --legacy-peer-deps
+      - run: npm ci
 
       - run: npm run lint-build
 

README.md

@@ -27,6 +27,53 @@ Repository for the Microservices API backend of the TerraMatch service
   - New `NEXT_PUBLIC_<SERVICE>_URL` values are needed for each service you're running locally. This will typically match
     the services defined in `V3_NAMESPACES` in `src/generated/v3/utils.ts`.
 
+# CLI
+
+We have a CLI app in this repo. Currently it's responsible for building and launching REPL processes locally and in the cloud.
+
+To build the CLI and make it executable:
+
+- `nx executable tm-v3-cli`
+- `(cd dist/tm-v3-cli; npm link)`
+
+The CLI may then be invoked as a direct shell command:
+
+- `tm-v3-cli -h`
+
+The verbose flag will put extra debugging output in the console:
+
+- `tm-v3-cli -v <command and args>`
+
+Development:
+
+- If you're working on active development of the CLI, you can run a build watcher:
+  - `nx build tm-v3-cli --watch --no-cloud`
+  - Note: starting this process will regenerate the `dist/tm-v3-cli` directory, which may remove the executable flag on the script.
+    If that happens, you can re-enable by running `nx exectuable tm-v3-cli` while the build watch command above is running.
+
+# REPL (local and in the cloud)
+
+We utilize the [Nest JS REPL](https://docs.nestjs.com/recipes/repl) to be able to access the code running in a given AWS
+environment, and use the same tools for local development.
+
+Start by following the steps above in the CLI section to get the CLI built and running locally.
+
+The command for running the REPL is simply `repl`:
+
+- `tm-v3-cli repl -h`
+
+The service name is required. The environment name is optional and will default to building and running the local REPL for that given service.
+
+If connecting to a remote REPL environment, the [AWS Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
+is required to be installed on your machine.
+
+As you will note on the NestJS documentation above, the REPL gives you access to all services exposed by your AppModule.
+In addition, the `boostrap-repl.ts` utility that is used by all services exposes a couple of things to make life a bit
+easier in the REPL env:
+
+- All of lodash accessible through `lodash` (e.g. `lodash.join([1, 2])`)
+- All database models are made accessible in the global context (e.g. `await User.findOne({ emailAddress: "[email protected]" })`)
+
 # Deployment
 
 Deployment is handled via manual trigger of GitHub actions. There is one for services, and one for the ApiGateway. The
@@ -48,12 +95,14 @@ and main branches.
   import "../../../instrument-sentry";
   ```
   - Add the `SentryModule` and `SentryGlobalFilter` to your main `app.module.ts`. See an existing service for an example.
+- Set up REPL access:
+  - Copy `repl.ts` from an existing service (and modify to specify the new service's name)
+  - Add the `build-repl` target to `project.json`, which an empty definition.
 - In your `.env` and `.env.local.sample`, add `_PORT` for the new service
 - In `api-gateway-stack.ts`, add the new service and namespace to `V3_SERVICES`
 - In your local web repo, follow directions in `README.md` for setting up a new service.
   - This step can be skipped for services that will not be used by the FE website.
 - For deployment to AWS:
-  - Add a Dockerfile in the new app directory. A simple copy and modify from user-service is sufficient
   - Add the new service name to the "service" workflow input options in `deploy-service.yml`
   - Add a new job to `deploy-services.yml` to include the new services in the "all" service deployment workflow.
     - Make sure to update the `check-services` step and follow the pattern for the `if` conditions on the individual service deploy jobs.

apps/entity-service/project.json

@@ -5,6 +5,7 @@
   "projectType": "application",
   "tags": [],
   "targets": {
+    "build-repl": {},
     "serve": {
       "executor": "@nx/js:node",
       "defaultConfiguration": "development",

apps/entity-service/src/entities/dto/entity-query.dto.ts

@@ -1,6 +1,8 @@
 import { ApiProperty, IntersectionType } from "@nestjs/swagger";
-import { IsEnum, IsOptional, ValidateNested } from "class-validator";
+import { IsArray, IsEnum, IsIn, IsInt, IsOptional, Max, Min, ValidateNested } from "class-validator";
 import { NumberPage } from "@terramatch-microservices/common/dto/page.dto";
+import { MAX_PAGE_SIZE, PROCESSABLE_ENTITIES, ProcessableEntity } from "../entities.service";
+import { Type } from "class-transformer";
 
 class QuerySort {
   @ApiProperty({ name: "sort[field]", required: false })
@@ -13,6 +15,18 @@ class QuerySort {
   direction?: "ASC" | "DESC";
 }
 
+export class EntitySideload {
+  @IsIn(PROCESSABLE_ENTITIES)
+  @ApiProperty({ name: "entity", enum: PROCESSABLE_ENTITIES, description: "Entity type to sideload" })
+  entity: ProcessableEntity;
+
+  @ApiProperty({ name: "pageSize", description: "The page size to include." })
+  @IsInt()
+  @Min(1)
+  @Max(MAX_PAGE_SIZE)
+  pageSize: number;
+}
+
 export class EntityQueryDto extends IntersectionType(QuerySort, NumberPage) {
   @ValidateNested()
   @IsOptional()
@@ -48,4 +62,23 @@ export class EntityQueryDto extends IntersectionType(QuerySort, NumberPage) {
   @ApiProperty({ required: false })
   @IsOptional()
   projectUuid?: string;
+
+  @ApiProperty({ required: false })
+  @IsOptional()
+  nurseryUuid?: string;
+
+  @ApiProperty({ required: false })
+  @IsOptional()
+  siteUuid?: string;
+
+  @ApiProperty({
+    required: false,
+    description: "If the base entity supports it, this will load the first page of associated entities",
+    type: [EntitySideload]
+  })
+  @IsArray()
+  @IsOptional()
+  @Type(() => EntitySideload)
+  @ValidateNested({ each: true })
+  sideloads?: EntitySideload[];
 }

apps/entity-service/src/entities/dto/nursery-report.dto.ts

@@ -0,0 +1,233 @@
+import { NurseryReport } from "@terramatch-microservices/database/entities";
+import { EntityDto, AdditionalProps } from "./entity.dto";
+import { pickApiProperties } from "@terramatch-microservices/common/dto/json-api-attributes";
+import { JsonApiDto } from "@terramatch-microservices/common/decorators/json-api-dto.decorator";
+import { ApiProperty } from "@nestjs/swagger";
+import { MediaDto } from "./media.dto";
+
+@JsonApiDto({ type: "nurseryReports" })
+export class NurseryReportLightDto extends EntityDto {
+  constructor(nurseryReport?: NurseryReport, props?: AdditionalNurseryReportLightProps) {
+    super();
+    if (nurseryReport != null) {
+      this.populate(NurseryReportLightDto, {
+        ...pickApiProperties(nurseryReport, NurseryReportLightDto),
+        lightResource: true,
+        // these two are untyped and marked optional in the base model.
+        createdAt: nurseryReport.createdAt as Date,
+        updatedAt: nurseryReport.updatedAt as Date,
+        ...props
+      });
+    }
+  }
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated nursery name"
+  })
+  nurseryName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated nursery uuid"
+  })
+  nurseryUuid: string | null;
+
+  @ApiProperty()
+  frameworkKey: string | null;
+
+  @ApiProperty()
+  frameworkUuid: string | null;
+
+  @ApiProperty()
+  status: string;
+
+  @ApiProperty()
+  updateRequestStatus: string;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated project name"
+  })
+  projectName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated project uuid"
+  })
+  projectUuid: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated organisation name"
+  })
+  organisationName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated organisation uuid"
+  })
+  organisationUuid: string | null;
+
+  @ApiProperty()
+  updatedAt: Date;
+
+  @ApiProperty({ nullable: true })
+  submittedAt: Date | null;
+
+  @ApiProperty({ nullable: true })
+  taskUuid: string | null;
+
+  @ApiProperty()
+  dueAt: Date | null;
+
+  @ApiProperty({ nullable: true })
+  title: string | null;
+
+  @ApiProperty({ nullable: true })
+  reportTitle: string | null;
+
+  @ApiProperty()
+  createdAt: Date;
+}
+
+export type AdditionalNurseryReportLightProps = Pick<NurseryReportLightDto, "reportTitle">;
+export type AdditionalNurseryReportFullProps = AdditionalNurseryReportLightProps &
+  AdditionalProps<NurseryReportFullDto, NurseryReportLightDto & Omit<NurseryReport, "nursery">>;
+export type NurseryReportMedia = Pick<NurseryReportFullDto, keyof typeof NurseryReport.MEDIA>;
+
+export class NurseryReportFullDto extends NurseryReportLightDto {
+  constructor(nurseryReport: NurseryReport, props?: AdditionalNurseryReportFullProps) {
+    super();
+    if (nurseryReport != null) {
+      this.populate(NurseryReportFullDto, {
+        ...pickApiProperties(nurseryReport, NurseryReportFullDto),
+        lightResource: false,
+        // these two are untyped and marked optional in the base model.
+        createdAt: nurseryReport.createdAt as Date,
+        updatedAt: nurseryReport.updatedAt as Date,
+        ...props
+      });
+    }
+  }
+
+  @ApiProperty({ nullable: true })
+  reportTitle: string | null;
+
+  @ApiProperty({ nullable: true })
+  projectReportTitle: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated nursery name"
+  })
+  nurseryName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated nursery uuid"
+  })
+  nurseryUuid: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated organisation name"
+  })
+  organisationName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated organisation uuid"
+  })
+  organisationUuid: string | null;
+
+  @ApiProperty()
+  dueAt: Date | null;
+
+  @ApiProperty()
+  status: string;
+
+  @ApiProperty()
+  updateRequestStatus: string;
+
+  @ApiProperty({ nullable: true })
+  feedback: string | null;
+
+  @ApiProperty({ nullable: true })
+  feedbackFields: string[] | null;
+
+  @ApiProperty()
+  nothingToReport: boolean;
+
+  @ApiProperty({ nullable: true })
+  completion: number | null;
+
+  @ApiProperty({ nullable: true })
+  title: string | null;
+
+  @ApiProperty({ nullable: true })
+  seedlingsYoungTrees: number | null;
+
+  @ApiProperty({ nullable: true })
+  interestingFacts: string | null;
+
+  @ApiProperty({ nullable: true })
+  sitePrep: string | null;
+
+  @ApiProperty({ nullable: true })
+  sharedDriveLink: string | null;
+
+  @ApiProperty({ nullable: true })
+  createdByFirstName: string | null;
+
+  @ApiProperty({ nullable: true })
+  createdByLastName: string | null;
+
+  @ApiProperty({ nullable: true })
+  approvedByFirstName: string | null;
+
+  @ApiProperty({ nullable: true })
+  approvedByLastName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated project name"
+  })
+  projectName: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated project uuid"
+  })
+  projectUuid: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description: "The associated task uuid"
+  })
+  taskUuid: string | null;
+
+  @ApiProperty({ nullable: true })
+  submittedAt: Date | null;
+
+  @ApiProperty()
+  migrated: boolean;
+
+  @ApiProperty()
+  createdAt: Date;
+
+  @ApiProperty()
+  updatedAt: Date;
+
+  @ApiProperty({ type: () => MediaDto, isArray: true })
+  file: MediaDto[];
+
+  @ApiProperty({ type: () => MediaDto, isArray: true })
+  otherAdditionalDocuments: MediaDto[];
+
+  @ApiProperty({ type: () => MediaDto, isArray: true })
+  treeSeedlingContributions: MediaDto[];
+
+  @ApiProperty({ type: () => MediaDto, isArray: true })
+  photos: MediaDto[];
+}