direct-file/direct-file/submit/README.md

# MEF Submit

If you use a proxy, first see `MAVEN_OPTS` in [the project readme](../README.md#important-configuration-variables) and [the OMB Connect readme](../README-omb-connect.md) for information about ensuring your proxy settings are passed to all build steps.

## Prerequisites

#### Setup dependencies and build

> [!NOTE]
> For setup please see the most up-to-date instructions which are found in the [Onboarding docs](../../ONBOARDING.md).

- Set an environment variable, `MEF_REPO`, whose value is the path where you want the MeF SDK repo cloned to. You can
set this up in your shell dotfile to have it loaded each time automatically. E.g.

    ```shell
    echo EXPORT MEF_REPO="~/irs/mef-sdk" >> ~/.zprofile
    ```

- Build and install the dependencies and build the submit app.

    ```sh
    INSTALL_MEF=1 ../scripts/build-project.sh
    ```

- Verify that java files exist in [the efile directory](./src/main/java/gov/irs/directfile/submit/xml/gov/irs/efile)

#### Running the application locally
- Follow the pre-requisite steps
- Set the 'MISSING' `application.yaml` properties. Setting test values for `etin`, `asid`, and `efin` listed below should work for local development where a connection to a MeF client is not required for your development work.
    NOTE: If you need to connect to the Mef client for your development work, you will need to use a separate set of variables, set the missing keystore values, and there may be additional setup specific to the MeF Client.
    ```yaml
    submit:
        etin: 11111
        asid: 22222222
        efin: 333333
    ```
- Run the application (you can do this from your IDE or the command line)
    ```sh
    # To use the command line run the following from the project root
    ./mvnw compile
    ./mvnw spring-boot:run -Dspring-boot.run.profiles=development
    ```
## Docker

Ensure that the appropriate environment variables are set up depending on how you are running the application.
See [environment](#environment) below.

Build the application:

```bash
docker compose build mef-submit
```

Then run it:

```bash
docker compose up -d mef-submit
```

The app probably failed for you due to lack of configuration.  You can look at the reason why it failed to start with:

```bash
docker compose logs mef-submit
```

## Running locally

### Environment

Set the following environment variables in your local environment which will facilitate running both the applications as well as the docker containers.  On MacBooks, placing the export statements below in the `.zshrc` (gets run and evaluated every time a shell instance is started) or `.zprofile` (gets run and evaluated when a user logs in) file will accomplish this.  If using the bash shell, placing them in `.bashrc` should do (and effectively behave similar to `.zshrc`).

```sh
# Get the base64 encoded keystore from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREBASE64="[base64-encoded-keystore]"

# Get the keystore password from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREPASSWORD="[keystore-password]"

# Get the keystore alias from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_KEYSTORE_KEYSTOREALIAS="[keystore-alias]"

# Get the ASID value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_ASID="[submit-asid]"

# Get the EFIN value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_EFIN="[submit-efin]"

# Get the ETIN value for the submit application from a fellow developer and replace the value in between quotes with the actual value
export SUBMIT_ETIN="[submit-etin]"

# Replace wa with your own initials *** NOTE: characters must be lowercase ***
export SUBMIT_ID_VAR_CHARS="wa"
```

You'll also need to set up the `LOCAL_WRAPPING_KEY` following the instructions in the [backend README](../backend/README.md#initial-setup)

```
export LOCAL_WRAPPING_KEY="[local-wrapping-key]"
```

Maven command for running the application locally:

```sh
./mvnw spring-boot:run -Dspring-boot.run.profiles=development
```

### Developer Notes

Files in the `direct-file/submit/src/main/java/gov/irs/directfile/submit/gen` directory are generated by the `direct-file/utils/mef-code-generator` application.

### Static Analysis

We use [SpotBugs](https://spotbugs.readthedocs.io/en/stable/bugDescriptions.html) and [PMD](https://pmd.github.io/pmd/index.html) for static code analysis in this app. The app is configured to have pre-commit hooks
run SpotBugs and PMD.

Spotbugs and PMD both generate static analysis reports that can be used to resolve issues in the project.

PMD is configured view an [xml file](src/main/resources/pmd/static-analysis-ruleset.xml) that specifies the linting rules we adhere to

**How do I see the reports?**

To see a formatted html page for the static analysis reports you can run:

```bash
./mvnw compile site:run
```

This will start a site at `localhost:9898`. Navigate to `Project Reports` and then click on PMD or Spotbugs to view errors in the app.

If you want to ignore the pre-commit hook that runs spotbugs do:

`git commit --no-verify`

To generate each  report, you can run:

```bash
./mvnw compile spotbugs:spotbugs
```

```bash
./mvnw pmd:pmd
```

The xml file this generates isn't very readable, so use `./mvnw spotbugs:gui` for an interactive guild or run `./mvnw site` to see an html report of the xml report.

To check if the project currently passes static analysis:

```bash
./mvnw compile spotbugs:check
```

```bash
./mvnw pmd:check
```

SpotBugs also offers a local gui that displays information based on the output of spotbugs. Calling compile before spotless:gui, ensures
we have all the latest changes reflected in the spotbugs report.

```bash
./mvnw compile spotbugs:gui
```

I've also configured the build to generate the spotbugs report when you run `./mvnw clean compile`. SpotBugs looks at the generated target folder
of the project, so doing a `./mvnw clean compile` will ensure you're seeing the latest spotbugs report.

For more information on Spotbugs:

Docs Site: https://spotbugs.readthedocs.io/en/latest/introduction.html

Github Repo: https://github.com/spotbugs/spotbugs

Maven Spotbugs Plugin Docs: https://spotbugs.github.io/spotbugs-maven-plugin/plugin-info.html

PMD Docs Site: https://docs.pmd-code.org/latest/index.html

PMD Java Rules: https://docs.pmd-code.org/latest/pmd_rules_java.html

PMD Maven Plugin Docs: https://maven.apache.org/plugins/maven-pmd-plugin/index.html

## Health Check

The Submit App uses [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/2.5.6/reference/html/actuator.html#actuator.endpoints.enabling) to expose a health check endpoint.
When running the app locally, the health check endpoint should be available at:

```text
http://localhost:{PORT}/actuator/health
```

## Tests

Run tests locally with `./mvnw test`