Reorganise Worker Module.

[davinchia]

What

I was reading this code when I realised this module is gradually developing into a sprawl. Reorganise to make this more readable and clarify certain operations.

A less-urgent follow up step here is to pull all process related code out of this module and combine it with the container-orchestrator module to achieve a clear split between 'job execution code' and 'process abstraction code'.

How

• Move all the worker implementations from top-level into the io.airbyte.workers.general package. Leave normalization related code in the normalization package as this is actually a special case of the dbt worker and should be deprecated once we implement general DBT support.
• Move all the general worker interfaces to the top level package to emphasis important interfaces.
• With this change, top level code in the airbyte workers module is now all interfaces + worker app set up code.
• Rename io.airbyte.workers.protocols.airbyte to io.airbyte.workers.internal to better represent this subpackage contains interfaces/implementations internal to the workers. Protocol is confusing since it implies some relation to the general airbyte protocol.
• Renameio.airbyte.workers.worker_run to io.airbyte.workers.run for conciseness.
• Merge io.airbyte.workers.test_helper to io.airbyte.workers.helper. Only a single class was present here.

Recommended reading order

The Github UI is somewhat useless for review due to the number of moved files. I recommend reviewing by browsing the airbyte-workers module in the IDE.

🚨 User Impact 🚨

Are there any breaking changes? What is the end result perceived by the user? If yes, please merge this PR with the 🚨🚨 emoji so changelog authors can further highlight this if needed.

Pre-merge Checklist

Expand the relevant checklist and delete the others.

New Connector

Community member or Airbyter

• Community member? Grant edit access to maintainers (instructions)
• Secrets in the connector's spec are annotated with airbyte_secret
• Unit & integration tests added and passing. Community members, please provide proof of success locally e.g: screenshot or copy-paste unit, integration, and acceptance test output. To run acceptance tests for a Python connector, follow instructions in the README. For java connectors run ./gradlew :airbyte-integrations:connectors:<name>:integrationTest.
• Code reviews completed
• Documentation updated
  • Connector's README.md
  • Connector's bootstrap.md. See description and examples
  • docs/SUMMARY.md
  • docs/integrations/<source or destination>/<name>.md including changelog. See changelog example
  • docs/integrations/README.md
  • airbyte-integrations/builds.md
• PR name follows PR naming conventions

Airbyter

If this is a community PR, the Airbyte engineer reviewing this PR is responsible for the below items.

• Create a non-forked branch based on this PR and test the below items on it
• Build is successful
• If new credentials are required for use in CI, add them to GSM. Instructions.
• /test connector=connectors/<name> command is passing
• New Connector version released on Dockerhub by running the /publish command described here
• After the connector is published, connector added to connector index as described here
• Seed specs have been re-generated by building the platform and committing the changes to the seed spec files, as described here

Updating a connector

Community member or Airbyter

• Grant edit access to maintainers (instructions)
• Secrets in the connector's spec are annotated with airbyte_secret
• Unit & integration tests added and passing. Community members, please provide proof of success locally e.g: screenshot or copy-paste unit, integration, and acceptance test output. To run acceptance tests for a Python connector, follow instructions in the README. For java connectors run ./gradlew :airbyte-integrations:connectors:<name>:integrationTest.
• Code reviews completed
• Documentation updated
  • Connector's README.md
  • Connector's bootstrap.md. See description and examples
  • Changelog updated in docs/integrations/<source or destination>/<name>.md including changelog. See changelog example
• PR name follows PR naming conventions

Airbyter

If this is a community PR, the Airbyte engineer reviewing this PR is responsible for the below items.

• Create a non-forked branch based on this PR and test the below items on it
• Build is successful
• If new credentials are required for use in CI, add them to GSM. Instructions.
• /test connector=connectors/<name> command is passing
• New Connector version released on Dockerhub and connector version bumped by running the /publish command described here

Connector Generator

• Issue acceptance criteria met
• PR name follows PR naming conventions
• If adding a new generator, add it to the list of scaffold modules being tested
• The generator test modules (all connectors with -scaffold in their name) have been updated with the latest scaffold by running ./gradlew :airbyte-integrations:connector-templates:generator:testScaffoldTemplates then checking in your changes
• Documentation which references the generator is updated as needed

Tests

Unit

Put your unit tests output here.

Integration

Put your integration tests output here.

Acceptance

Put your acceptance tests output here.

[jdpgrailsdev]

Huge +1 on the rename from protocol to internal to represent interfaces not used outside of the worker module. I hope that we will do more of this to help convey better which code is used outside of a given module.

[benmoriceau]

LGTM overall. I just have a concern about the naming of the general packages and its content. Shouldn't the interface and their implementation be in the same package? For the naming I think that runners would be better than general

Also should we move the interface within the module that implements them?

Not entirely related to this review but we can extract the custom exception in their own module as well.

I made #12959 that contains those changes if you want to see what it would looks like.

[davinchia]

thanks for the feedback @benmoriceau !

Not entirely related to this review but we can extract the custom exception in their own module as well.

Sounds good.

For the naming I think that runners would be better than general

I did think about this. 'runners' felt more confusing to me since there is a 'normalisation' package. It felt more natural to have a package representing 'normal operations' i.e. general and the normalisation as a special case. Can we keep it as is and rename to runner when we get rid of normalisation?

Also should we move the interface within the module that implements them?

It's pretty common to see interfaces be separate from the implementation in a protocol or api package (e.g. the SLF4J api and the LOG4J implementation is an extreme example) so I think keeping them separate is accepted practice. My goal here is to organise things so someone can browse the worker module and at a glance know what important classes/interfaces are without opening any directories. To me, moving the interfaces down a level isn't as clear and clutters up the implementation module directory. I'm also happy to place these interfaces in a specific interface folder. What do you think?

[benmoriceau]

thanks for the feedback @benmoriceau !

Not entirely related to this review but we can extract the custom exception in their own module as well.

Sounds good.

For the naming I think that runners would be better than general

I did think about this. 'runners' felt more confusing to me since there is a 'normalisation' package. It felt more natural to have a package representing 'normal operations' i.e. general and the normalisation as a special case. Can we keep it as is and rename to runner when we get rid of normalisation?

Also should we move the interface within the module that implements them?

It's pretty common to see interfaces be separate from the implementation in a protocol or api package (e.g. the SLF4J api and the LOG4J implementation is an extreme example) so I think keeping them separate is accepted practice. My goal here is to organise things so someone can browse the worker module and at a glance know what important classes/interfaces are without opening any directories. To me, moving the interfaces down a level isn't as clear and clutters up the implementation module directory. I'm also happy to place these interfaces in a specific interface folder. What do you think?

I did think about this. 'runners' felt more confusing to me since there is a 'normalisation' package. It felt more natural to have a package representing 'normal operations' i.e. general and the normalisation as a special case. Can we keep it as is and rename to runner when we get rid of normalisation?

Yes it sounds good.

It's pretty common to see interfaces be separate from the implementation in a protocol or api package (e.g. the SLF4J api and the LOG4J implementation is an extreme example) so I think keeping them separate is accepted practice. My goal here is to organise things so someone can browse the worker module and at a glance know what important classes/interfaces are without opening any directories. To me, moving the interfaces down a level isn't as clear and clutters up the implementation module directory. I'm also happy to place these interfaces in a specific interface folder. What do you think?

I would prefer having it in our root rather than in a dedicated package. I was think about moving to the same package because at the moment we on use those interface in the general package.

[benmoriceau]

Avoid blocking
Edit: didn't remove the change requested

[davinchia]

@benmoriceau I moved it the exceptions into it's own package. I decided to moving all the specific interfaces into the general package isn't a bad idea so did it!