Merge pull request #875 from wasp-lang/vince-update-docs-workers-auth

Update features.md

web/docs/deploying.md

@@ -332,8 +332,7 @@ Now go back to your terminal and execute the following commands:
   Select `server` when prompted with `Select Service`. Press enter.
   Railway will now locate the Dockerfile and deploy your server 👍
 
-  When deployment is finished, you will see: `Deployment live at <url_to_wasp_backend>`
+  When deployment is finished, you might see: `Deployment live at <url_to_wasp_backend>`. If not, go now to your [Railway dashboard](https://railway.app/dashboard) and in the server instance's `Settings` tab, click `Generate Domain`. Copy the new URL as we will need it for step 5! 📜
-  Copy this URL 📜. We need it for step 5!
 
   4. Next, change into your app's frontend build directory `.wasp/build/web-app`:
   ```shell
@@ -348,13 +347,19 @@ Now go back to your terminal and execute the following commands:
   ✅ https://backend.example.com <br/>❌ https://backend.example.com/ 
   :::
 
-  6. Change into the `.wasp/build/web-app/build` directory and deploy:
+  6. Change into the `.wasp/build/web-app/build` directory:
   ```shell
-  cd build && railway up
+  cd build 
   ```
-  This time select `client` when prompted with `Select Service`. 
+  7. Next, we want to link this specific frontend directory to our project as well:
-
+  ```shell
-  7. Your apps are deployed 🧙‍♂️. Now it's time to add environment variables, so open the project in the browser
+  railway link 
+  ```
+  8. Deploy the client and select `client` when prompted with `Select Service`:
+  ```shell
+  railway up
+  ```
+  9. Your apps are deployed 🧙‍♂️. Now it's time to add environment variables, so open the project in the browser
   ```shell
   railway open
   ```
@@ -392,6 +397,9 @@ Next, copy the server's domain, move over to the client's `Variables` tab and ad
 
 And now you should be deployed! 🐝 🚂 🚀
 
+#### Updates & Redeploying
+When you make updates and need to redeploy, just follow [steps 3-7](#deploy-to-services) above. Remember, you can connect or disconnect your app to any project in your Railway account by using `railway link` or `railway unlink` from within the app's directory.
+
 ## Customizing the Dockerfile
 By default, Wasp will generate a multi-stage Dockerfile that is capable of building an image with your Wasp-generated server code and running it, along with any pending migrations, as in the deployment scenario above. If you need to customize this Dockerfile, you may do so by adding a Dockerfile to your project root directory. If present, Wasp will append the contents of this file to the _bottom_ of our default Dockerfile.
 
@@ -403,6 +411,3 @@ Since the last definition in a Dockerfile wins, you can override or continue fro
 To see what your project's (potentially combined) Dockerfile will look like, run: `wasp dockerfile`
 
 Here are the official docker docs on [multi-stage builds](https://docs.docker.com/build/building/multi-stage/). Please join our Discord if you have any questions, or if the customization hook provided here is not sufficient for your needs!
-
-#### Updates & Redeploying
-When you make updates and need to redeploy, just follow [steps 3-7](#deploy-to-services) above. Remember, you can connect or disconnect your app to any project in your Railway account by using `railway link` or `railway unlink` from within the app's directory.

web/docs/language/features.md

@@ -583,7 +583,13 @@ import { isPrismaError, prismaErrorToHttpError } from '@wasp/utils.js'
 
 ## Jobs
 
-If you have server tasks that you do not want to handle as part of the normal request-response cycle, Wasp allows you to make that function a `job` and it will gain some "superpowers." Jobs will persist between server restarts, can be retried if they fail, and they can even be delayed until the future (or have a recurring schedule)! Some examples where you may want to use a `job` on the server include sending an email, making an HTTP request to some external API, or doing some nightly calculations.
+If you have server tasks that you do not want to handle as part of the normal request-response cycle, Wasp allows you to make that function a `job` and it will gain some "superpowers." Jobs will:
+  * persist between server restarts
+  * can be retried if they fail
+  * can be delayed until the future
+  * can have a recurring schedule! 
+  
+Some examples where you may want to use a `job` on the server include sending an email, making an HTTP request to some external API, or doing some nightly calculations.
 
 ### Job Executors
 
@@ -597,7 +603,8 @@ Currently, Wasp supports only one type of job executor, which is `PgBoss`, but i
 
 We have selected [pg-boss](https://github.com/timgit/pg-boss/) as our first job executor to handle the low-volume, basic job queue workloads many web applications have. By using PostgreSQL (and [SKIP LOCKED](https://www.2ndquadrant.com/en/blog/what-is-select-skip-locked-for-in-postgresql-9-5/)) as its storage and synchronization mechanism, it allows us to provide many job queue pros without any additional infrastructure or complex management.
 
-Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details for more information.
+:::info 
+Keep in mind that pg-boss jobs run alongside your other server-side code, so they are not appropriate for CPU-heavy workloads. Additionally, some care is required if you modify scheduled jobs. Please see pg-boss details below for more information.
 
 <details>
   <summary>pg-boss details</summary>
@@ -617,6 +624,7 @@ Keep in mind that pg-boss jobs run alongside your other server-side code, so the
 - https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js
 
 </details>
+:::
 
 ### Basic job definition and usage
 
@@ -626,7 +634,7 @@ To declare a `job` in Wasp, simply add a declaration with a reference to an `asy
 job mySpecialJob {
   executor: PgBoss,
   perform: {
-    fn: import { foo } from "@server/jobs/bar.js"
+    fn: import { foo } from "@server/workers/bar.js"
   }
 }
 ```
@@ -645,6 +653,8 @@ await mySpecialJob.delay(10).submit({ job: "args" })
 
 And that is it! Your job will be executed by the job executor (pg-boss, in this case) as if you called `foo({ job: "args" })`. 
 
+Note that in our example, `foo` takes an argument, but this does not always have to be the case. It all depends on how you've implemented your worker function. 
+
 ### Recurring jobs
 
 If you have work that needs to be done on some recurring basis, you can add a `schedule` to your job declaration:
@@ -653,7 +663,7 @@ If you have work that needs to be done on some recurring basis, you can add a `s
 job mySpecialJob {
   executor: PgBoss,
   perform: {
-    fn: import { foo } from "@server/jobs/bar.js"
+    fn: import { foo } from "@server/workers/bar.js"
   },
   schedule: {
     cron: "0 * * * *",
@@ -662,7 +672,7 @@ job mySpecialJob {
 }
 ```
 
-In this example, you do _not_ need to invoke anything in JavaScript. You can imagine `foo({ "job": "args" })` getting automatically scheduled and invoked for you every hour.
+In this example, you do _not_ need to invoke anything in JavaScript. You can imagine `foo({ job: "args" })` getting automatically scheduled and invoked for you every hour.
 
 ### Fully specified example
 Both `perform` and `schedule` accept `executorOptions`, which we pass directly to the named job executor when you submit jobs. In this example, the scheduled job will have a `retryLimit` set to 0, as `schedule` overrides any similar property from `perform`. Lastly, we add an entity to pass in via the context argument to `perform.fn`.
@@ -670,9 +680,8 @@ Both `perform` and `schedule` accept `executorOptions`, which we pass directly t
 ```c
 job mySpecialJob {
   executor: PgBoss,
-  entities: [Task],
   perform: {
-    fn: import { foo } from "@server/jobs/bar.js",
+    fn: import { foo } from "@server/workers/bar.js",
     executorOptions: {
       pgBoss: {=json { "retryLimit": 1 } json=}
     }
@@ -683,7 +692,8 @@ job mySpecialJob {
     executorOptions: {
       pgBoss: {=json { "retryLimit": 0 } json=}
     }
-  }
+  },
+  entities: [Task],
 }
 ```
 
@@ -695,7 +705,7 @@ job mySpecialJob {
 ####  `perform: dict` (required)
 
   - ##### `fn: ServerImport` (required)
-  An `async` JavaScript function of work to be performed. Since Wasp executes jobs on the server, you must import it from `@server`. The function receives a JSON value as the first argument and context containing any declared entities as the second. Here is a sample signature:
+  An `async` JavaScript function of work to be performed. Since Wasp executes jobs on the server, you must import it from `@server`. The function receives a first argument which may be passed when the job is called, as well as the context containing any declared entities as the second (this is passed automatically by Wasp). Here is a sample signature:
 
   ```js
   export async function foo(args, context) {
@@ -714,6 +724,8 @@ job mySpecialJob {
   - ##### `cron: string` (required)
   A 5-placeholder format cron expression string. See rationale for minute-level precision [here](https://github.com/timgit/pg-boss/blob/8.0.0/docs/readme.md#scheduling).
   
+  _If you need help building cron expressions, Check out_ <em>[Crontab guru](https://crontab.guru/#0_*_*_*_*).</em>
+  
   - ##### `args: JSON` (optional)
   The arguments to pass to the `perform.fn` function when invoked.