mirror of https://github.com/microsoft/PowerToys.git synced 2024-12-27 03:14:18 +08:00

[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

2023-07-18 10:44:02 +01:00

3.8 KiB

Raw Blame History

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.

`IComputeRequest`

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`

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() will need to return a HashRequest for the algorithm in the query

`Base64Request`

Implements IComputeRequest
Compute() will populate Result with the base64 encoding of the byte array passed in the constructor

`GUIDRequest`

Implements IComputeRequest
Uses the GUIDGenerator class to generate or compute the requested GUID

`GUIDGenerator`

Utility class for generating or calculating GUIDs
Generating GUID versions 1 and 4 is done using builtin APIs. 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
The PredefinedNamespaces dictionary contains aliases for the predefined namespaces
The name can be any string

`InputParser`

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

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.
Add any utility classes that are specific to the new generator inside the same folder to keep them separated from the other generators.
Modify the InputParser.ParseInput() to handle a request for the new generator and return an instance of the class you created in step 1

3.8 KiB Raw Blame History

Value Generator Plugin

IComputeRequest

HashRequest

Base64Request

GUIDRequest

GUIDGenerator

InputParser