jsonhash 0.2.0

# jsonhash

A command-line tool to compute hash of file content and filepath, returning the result as JSON.

## Supported hashing algorithms

- SHA256: Recommended to avoid collision. By default.
- MD5: Fast (but unsafe) - suitable for files - provided for compatibility/legacy purposes

## Features

- Supports both SHA256 and MD5 hash algorithms
- Computes hash of file content
- Computes hash of absolute filepath
- Computes hash of short path (relative to current directory). Useful to create bucket/file ids.
- Returns all information in JSON format. Output and Error messages in JSON format.
- Adopted a request/response style output (>= version 0.2.0)

## Usage

- The -a|--alg flag is optional. SHA256 by default

### Compute SHA256 hash (default)

```bash
jsonhash <filepath>
```

### Compute MD5 hash

```bash
jsonhash -a md5 <filepath>
```

```bash
jsonhash --alg md5 <filepath>
```

### Compute SHA256 hash (explicit)

```bash
jsonhash -a sha256 <filepath>
```

```bash
jsonhash -alg sha256 <filepath>
```

### Response

The tool returns a JSON object with the following fields:

- `request`: the request object
- `response`: the response object
- `error`: the error object

#### Notes

`request` always is present.
`response` and `error` are mutually exclusive.

### Request object

- `method`: the name of this tool. 'jsonhash'
- `version`: the version of this tool
- `ts`: timestamp in nanoseconds when the request was received
- `params` : contains the parameters as "key":value
  - `filepath`: filepath you provided in your request
  - `alg`: Algorithm used (sha256 or md5)
  - `id`: value provided with --id, else null

### Response object

- `ts`: timestamp in nanoseconds when the request was responded
- `absfilepath`: Absolute path of the file
- `hash`: Hash of the file content
- `filename`: Name of the file
- `shortpath`: Short path relative to current directory
- `pathid`: Hash of the absolute filepath
- `shortpathid`: Hash of the short path

## Example

```bash
jsonhash test.txt
```

Returns:

```json
{
  "request": {
    "method": "jsonhash",
    "params": {
      "filepath": "test.txt",
      "id": "1",
      "alg": "md5"
    },
    "ts": 1760367864236976611,
    "version": "0.2.0"
  },
  "response": {
    "ts": 1760367864237186637,
    "absfilepath": "/tmp/jsonhash/test.txt",
    "hash": "9458edef495a29ee98b40a63ed80e9b7",
    "filename": "test.txt",
    "shortpath": "jsonhash/test.txt",
    "pathid": "50b53521888c464428cbb6189ef50602",
    "shortpathid": "d746f98d3344150895a94a752349ce82"
  }
}
```

## Error messages

- Error messages are provided in json format

`error` message will contain:
  `code`: code at integer
  `message`: error message as String

| Code | Value | Description |
| ---- | ----- | ----------- |
| 3 | HASH-ALGORITHM-INVALID | incorrect / unsupported hash algorithm |
| 5 | NOT-A-FILE | The filepath is not a file (Directories are not supported) |
| 6 | FILE-DOES-NOT-EXIST | The filepath does not exist. No such address: The specified address is unavailable. |
| 66 | FILE-OPENING-ERROR | file cannot be opened |
| 70 | HASH-DIGEST-COMPUTATION-ERROR | An error occured during the computation of the hash digest |

```json
{
  "request": {
    "method": "jsonhash",
    "params": {
      "filepath": "/temp/non-existing-file",
      "id": null,
      "alg": "sha256"
    },
    "ts": 1760368083128138305,
    "version": "0.2.0"
  },
  "error": {
    "code": 6,
    "message": "FILE-DOES-NOT-EXIST"
  }
}

```

## Dependencies

- Rust
- sha2 crate for SHA256 hashing
- md5 crate for MD5 hashing
- clap for command-line argument parsing
- serde for JSON serialization
- tempfile for testing

## Building

```bash
cargo build --release
```

## Testing

```bash
cargo test
```

- A test.txt sample file is included: `test.txt`
- A bash test script that uses the sample file is included: `test.sh`

## License

[MIT](mit.txt) or [Apache2](license.txt)

## Author

[David HEURTEVENT - frua.fr](https://github.com/fruafr)

## Changelog

- Version 0.2.0 : Breaking compatibility with v.0.1.x : New JSON request-reponse style with versioning and timestamps (consistent with the [jfsm](https://crates.io/crates/jfsm/versions) library).