[PTRun]New plugin: Value generator with hashing functions (#26097)

* Add hashing plugin for Run

* Cleanup logic for hasher plugin

- The IComputeRequest interface should make it easier to implement new
  generators in the future
- The GUID generator can now generate all versions of GUID (a.k.a. UUID)
- The input for the hash functions is not quite right. The
  Wox.Plugin.Query class doesn't actually have a way to ge the raw query
  as given by the user. The issue is with multiple spaces. An input like
  "a a  a    a    a" would only be accessible as "a a a a a" using the
  Query class.
  So for now, hashing only works correctly if the input
  doesn't contain multiple consecutive spaces.
- Need a way to make clear the usage for generating GUIDv3 and v5, since
  they take 2 parameters. There are defaults, but they aren't very
  clear.

* Change plugin name to ValueGenerator

* Clean up error handling for the input parser

* Add result type and description to subtitle

* Change the icons

* Add Base64 encoding and unit tests

This commit adds Base64 encoding as a utility of the value generator
plugin. The command is `# base64 ***input***`.

Also added unit tests for the UUID/GUID generator and for the input
parser. I don't think tests are necessary for the hashing functions
or for the base64 encoder, since those were part of the the system
libraries.

I'll open a PR for the documentation tomorrow and mark this draft
for review.

* Excluded UUIDv2

* Change icons

* Add RawUserQuery to Wox.Plugin.Query

Getting the RawUserQuery is necessary to be able to handle queries like
`# md5 a    a`, where the intent is to get the hash for `a    a`.
The existing `RawQuery` removes consecutive whitespaces and there was no
other way of getting the request as entered by the user.

* Add ValueGenerator plugin to installer

Also add the unit tests for the plugin to the pipeline.

* Small cleanup

* Fix spelling

* Fix spelling again

* Spell check for guiddata

* More fixes

This commit adds the dev docs explaining the classes in the new plugin.
It also fixes the following issues:
1. ValueGenerator was not a dependency for the PowerLauncher project
2. The error message for an invalid SHA variant now displays the
   supported SHA variants
3. Hash requests now wait for a string to hash (i.e. no longer hash an
   empty string)
4. GUID v3 and v5 namespace aliases allow lowercase notation
5. Unnecessary debug logs
6. An empty query will now just log "Empty request"
7. An invalid query will also log user query

* Spell check fix again

* Change error message for unsupported GUID versions

* Remove Any CPU from the solution

* Add to installer

* Remove duplicated ValueGeneratorPluginFolder entry
This commit is contained in:
Tudor Croitoru
2023-07-18 10:44:02 +01:00
committed by GitHub
parent 9eea08d8a8
commit 602368f6cc
30 changed files with 1458 additions and 2 deletions

View File

@@ -0,0 +1,52 @@
# Value Generator Plugin
The Value Generator plugin is used to generate hashes for strings, to calculate base64 encodings and to generate GUIDs versions 1, 3, 4 and 5.
![Image of Value Generator plugin](/doc/images/launcher/plugin/community.valuegenerator.png)
### [`IComputeRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/IComputeRequest.cs)
- Interface for a request for computation
- the `bool Compute()` method must populate the `IsSuccessful` and one of the `Result` and `ErrorMessage` fields
- The result of `string ResultToString()` will be used for the Result's title
- The `Description` field will be used for the Result's subtitle
### [`HashRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Hashing/HashRequest.cs)
- Implements IComputeRequest
- Supports the hashing algorithms from System.Security.Cryptography:
- MD5
- SHA1
- SHA256
- SHA384
- SHA512
- If other algorithms are added to System.Security.Cryptography, they can be added to the `_algorithms` dictionary. [`InputParser.ParseInput()`](#inputparser) will need to return a `HashRequest` for the algorithm in the query
### [`Base64Request`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Base64/Base64Request.cs)
- Implements IComputeRequest
- `Compute()` will populate `Result` with the base64 encoding of the byte array passed in the constructor
### [`GUIDRequest`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDRequest.cs)
- Implements IComputeRequest
- Uses the [`GUIDGenerator`](#guidgenerator) class to generate or compute the requested GUID
### [`GUIDGenerator`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GUID/GUIDGenerator.cs)
- Utility class for generating or calculating GUIDs
- Generating GUID versions 1 and 4 is done using builtin APIs. [`UuidCreateSequential`](https://learn.microsoft.com/en-us/windows/win32/api/rpcdce/nf-rpcdce-uuidcreatesequential) for version 1 and `System.Guid.NewGuid()` for version 4
- Versions 3 and 5 take two parameters, a namespace and a name
- The namespace must be a valid GUID or one of the [predefined ones](https://datatracker.ietf.org/doc/html/rfc4122#appendix-C)
- The `PredefinedNamespaces` dictionary contains aliases for the predefined namespaces
- The name can be any string
### [`InputParser`](/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/InputParser.cs)
- It is responsible only for parsing the query from the user
- Based on the user query, the `ParseInput()` method must return an object that implements the `IComputeRequest` interface or it must throw one of `FormatException` or `ArgumentException`
- Throwing an `ArgumentException` should signal the fact the query contains a mistake that the user can fix (eg. an unsupported hash function, an invalid GUID version, an invalid namespace, etc)
> The error message will be shown to the user and no log message will be created
- Throwing a `FormatException` should signal either:
- that the query may become valid, and so it does not make sense to show an error just yet (eg. the query does not contain a request yet, a hash request without a string to hash)
- that the query is completely invalid
> The error message will not be shown to the user but a log message will be created
### Adding a new value generator
1. To add a new value generator, create a folder under `/src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/` and inside it add a class that implements `IComputeRequest`.
2. Add any utility classes that are specific to the new generator inside the same folder to keep them separated from the other generators.
3. Modify the `InputParser.ParseInput()` to handle a request for the new generator and return an instance of the class you created in step 1