[ Documentation request ] Add "polyglot" usage to dev guide

[mjameswh]

Brief description

Dev guides should include explanations of cross-SDK usages. Doc would follow a similar structure for all languages, but explanations and code example would have to be tailored to each language.

We have a few samples of polyglot usage scenarios here and there, but they are mostly "proof of concept", providing no explanation and no guidance on how to replicate. They also grow quite inefficiently relative to the number of languages (need ~NxNx8 samples to cover all combinaissons, but ~Nx8 samples to document it thoroughly).

Your recommended content

Note: The text below has been extracted from a Slack conversation regarding TS Workflows calling Python activities.

• General considerations
  • Temporal makes it very easy to combine parts written in various language. One of the key strength of Temporal.
  • Worker developed in different languages implies different task queues
  • Different languages have different conventions regarding function naming, and different SDKs may have different rules regarding how function names relate to activity types. When doing calling workflow or activities across SDK, you may need to either force the activity type on the activity worker, or use the correct syntax of the Activity Type on the Workflow side. Examples on doing both of these for $thisLanguage in sections below.
  • SDKs should generally encode/decode args and return values correctly, but cross-SDK calls may expose differences in how various JSON libraries handle some particular cases. You should therefore be more cautious in defining your data structures. Only use simple types that are natively understood by JSON. Beware of “big integers”, dates, etc.
  • SDK will correctly route errors thrown from activities back to the Workflow. You may however note some discrepancies in how “language native” errors get encoded/decoded. Make sure you test error handling properly.
• Using a client in $thisLanguage to start/execute a Workflow in another language
  • Using startWorkflow/executeWorkflow directly (ie. workflow type as a string)
  • Using "stub workflow definitions" (possible in most SDKs)
• Executing "Workflows" written in $thisLanguage from another language
  • How Workflow Types in $thisLanguage are determined from a function (by default)
  • How to specifically change the Workflow Type of a Workflow function (possible in most SDKs)
• Using a Workflow in $thisLanguage to execute an Activity in another language
  • Using scheduleActivity directly (ie. activity type as a string) — This is a little bit easier, but you get absolutely no type safety checking on the Workflow side. Simply call scheduleActivity, with the activity name and args. You will also need to provide the task queue name and timeout.

    const result: MyActivityResultType = await scheduleActivity('myActivity', [{ phoneNumber: '514-555-1234', address: '....' }], {
      taskQueue: 'my-python-worker-taskqueue',
      scheduleToCloseTimeout: '10m',
      // ...
    });
    

  • Using "stub activity definitions" (possible in most SDKs)

    interface MyPythonActivities {
      myActivity: (arg1: { phoneNumber: string; address: string }) => MyActivityResultType;
    }
    
    const {myActivity} = proxyActivities<MyPythonActivities>({ taskQueue: 'my-python-worker-taskqueue', scheduleToCloseTimeout: '10m' });
    
    async function myWorkflow(...) {
       ...
       // Your Workflow may call `myActivity` just the same as if it was a TS activity!
       const result = await myActivity({ ... });
       ...
    }
    

• Child workflows in another language from parent in $thisLanguage
• Child workflows in $thisLanguage from a parent Workflow in another language
• Signals...
• Queries...

[cretz]

I think for a basic starter here, you can just show the same activity (name and types) in each lang and a sample workflow calling it from each lang (including the interfaces/mocks representing the activity). Then you can explain the caveats about conversion, task queue, etc.