sample: working with Optic

[LouManglass]

Howdy! I'm Lou with Optic, and I've been following along in the Managing changes discussion. I wanted to provide a sample of how Optic could fit into your project and get some feedback. I know it's a bit of a challenge to engineer this in after the fact, and hopefully this is inspirational as to what could be. I'll be happy to help refine this sample further.

Here's a 5 minute demo if you'd like to see the end result first.

Optic sample

Looking at the local development environment, and from an understanding gained in the Optic discussion #469, I thought it would be best to capture the requests proxied from the vue web server to the API server run by nodemon:

---------------     ---------------
| Vue web svr | ==> | nodemon app |
---------------     ---------------

Becomes

---------------     ---------------     ---------------
| Vue web svr | ==> | Optic Proxy | ==> | nodemon app |
---------------     ---------------     ---------------

This lets Optic focus on the API for the project, and not on local browser traffic. It also will catch traffic regardless of whether it originates from localhost or another IP, reducing confusion. If you want to observe traffic to the front-end application, we'd have to set that up slightly differently.

Constraints

Based on the feedback in the Optic discussion #469, I focused on the following elements for local development:

• Stick Optic in devDependencies
• Minimize impact so it's not harder for new contributors to set up/run locally
• Be able to attach a debugger (used Visual Studio Code)

I didn't cover some other feedback in this sample:

• The command is still api here for now.
• Optic still expects to generate a fresh spec.

Running OpenTogetherTube with Optic in development

To run Optic with OpenTogetherTube, I made a few small chanegs:

• package.json
  • Added Optic as a devDependency
  • Updated dev script to keep the vue front-end on port 8080. This allows Optic to pass a port through for the api-server, so Optic can act as a proxy on port 3000, while not interrupting vue's environment. The same would have to be done for Windows, and this would only work for development. For production modes, we can revisit what makes the most sense.
  • Added two npm scripts, optic-dev and optic-test to run the dev and test scripts with Optic, respectively. Alternatively, npx api start and npx api run tests would work directly.

This starts the vue front-end on port 8080 as expected, which proxies /api traffic to port 3000. Optic picks up the traffic, observes it, and forwards it on to the back-end which runs on an Optic-assigned port at startup (e.g. 3486). When changes are made, nodemon still has the Optic-assigned port and restarts accordingly.

Debugging

This required a bit more work to implement, and to avoid contaminating any current run configurations (to allow for comparison), I created a new launch configuration. Launch with Optic via NPM will run a third npm script, optic-api-server, which in turn runs npx api run api-server to kick off the api-server. This would take the place of Launch Program > Start. The developer would still need to run npm run serve to run the client.

Putting it all together

Here's a 5 minute demo

Remaining work

This can be cleaned up a bit. I tried not to mess with existing tooling, such as concurrently. I also didn't do anything for development on Windows, which would follow the same pattern (or may be supported by a tool such as cross-env. I didn't want to go too far before seeing how useful this sample was. However, much of this could be consolidated and streamlined to fit the desired workflow.

[dyc3]

WOW! Everything I could have asked for and more! This will help a ton. I'm absolutely floored by the amount of support y'all have given me. Thank you so much! I'll probably end up pulling that commit into my local branch where I'm currently working on the api docs.

[LouManglass]

You're very welcome, we really appreciate you taking the time to contribute to our discussions. Not to sound like some big company, but we truly do appreciate your thoughts and time, and we're interested in hearing more as you play around with Optic. If we can help you get past any hurdles or answer any questions, please let me know. I'm happy to put in some time so that we can hear your thoughts.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication