Merge pull request #1 from hurricanemark/Phase1-Extended-Weather-Forecasts

Phase1 extended weather forecasts

Author: hurricanemark

README.md

@@ -0,0 +1,150 @@
+# Weather Service
+
+Ever wonder why your phone shows weather data of your immediate vicinity on your travel?  This project demonstrates the use of Navigator.geolocation API that is part of NodeJS to pinpoint your immediate location.  The geolocation method gets the current position in longitude and latitude.  The weather app uses these values to call a weather service API for weather data.  This non-interactive process happens automatically for your convenience.
+
+## The Value of Weather Information 
+
+Weather information is powerful knowledge used in forecasting the production of certain operations to help determine the economic bottom line.  There are countless human endeavors affected by weather factors.  Rain is good for growers, and forewarning is valuable in extreme weather, while the sunny sky and windy days could be good for energy production.  For example, solar power production needs to know the number of hours of sunlight specific to geographical location.  Wind farm needs to know wind speed, direction, etc. The travel and hospitality industry is most affected by dynamic weather patterns.  From Agriculture to space-faring, weather plays a key role in the decision-making process.
+
+There are weather detection stations situated in and around you.  The inner working of making data available is not of interest to the populous but it is vital to a functioning society.  Although, the National Weather Service is a government agency that disseminates data free of charge.  Weather data has been monetized by repackaging in ways the population can consume.  e.g. Local TV news reserve a segment devoted to weather ubiquitously.  Weather data is available at your finger tips.  It is all factored into a transferable cost by some service providers you're currently paying.
+
+<br />
+
+> Below is the template for rudimentary completion of an example on interfacing with a weather data provider.  For indepth logics and real life data implementation, continue to [here](public/README.md).
+
+<br />
+
+## NodeJS and Express
+
+I recently wrote this weather reporting app using the cloud editor `replit` where the bootstraping of node JS is hidden.  All I had to do was to focus on the core logic in app.js, style.css, and index.html.  To create a fully functional development environment locally, I needed to bootstrap NodeJS, Express to my replit code.  
+
+Here is how I add scalffolding my Nodejs project.
+
+**Configure Project Development Environment for ES6**
+
+>Let's assume you are using NodeJS with a version later than 13.  Then, it is required to configure the development environment to work for ExpressJS with dotenv and ES6 modules.
+
+First, you will need to change your `package.json` to include:
+
+```c
+...
+"type": "module",
+...
+```
+
+Then, use imports in your `app.js`.  Here is an express start with dotenv:
+
+```c
+import dotenv  from "dotenv"
+import express from "express"
+
+dotenv.config()
+
+const app = express()
+const port = process.env.PORT || 5000
+
+app.get('/', (req, res) => {
+  res.send("Local Weather.  Don't leave home without reading it")
+})
+
+app.listen(port, () => {
+  console.log(`Local weather server is serving you from http://0.0.0.0:${port}`)
+})
+```
+
+<br />
+
+Step 1:  Migrate replit code to local VSCode.
+    Create a folder for your project.  Create sub folders `views` and `public` to place client-side programming. 
+    
+    `mkdir views`
+
+    `mkdir public`
+
+Step 2:  Initialize the folder as a node project
+    
+    ` npm init -y`
+
+Step 3:  Install *express* to confiure a lightweight Node server
+    
+    `npm install express`
+
+Step 4:  Install *helmet* to configure runtime security
+    
+    `nmp install helmet`
+
+Now, you are good to start developing and runing from VSCode.
+
+### Project Layout
+
+It is a typical NodeJS project layout.  
+
+'app.js' - server file
+
+'./public/script.js' - interface to https://weather-proxy.freecodecamp.rocks/api/
+
+'./views/index.html' - client-side presentation. 
+
+## Runtime
+
+`npm start`
+
+<strong>Output</strong>
+
+![codepen.io output](./public/Runtime.PNG)
+
+## Build and Run Docker Image
+
+Build a docker image base on the given Dockerfile and .dockerignore is this folder.  After successful docker build, run the image to verify correctness.  Then it can be pushed to dockerhub or your favorite cloud provider.  
+
+### Build
+Docker container is built and saved to current working directory.  Replace tag name 'hurricanemark' with your own username.
+
+`docker build -t hurricanemark/localweather:1.0 .`
+
+```c
+[+] Building 139.3s (11/11) FINISHED
+ => [internal] load build definition from Dockerfile                                              0.1s 
+ => => transferring dockerfile: 210B                                                              0.1s 
+ => [internal] load .dockerignore           
+...
+ => [internal] load build context                                                                 0.8s 
+ => => transferring context: 143.24kB                                                             0.6s 
+ => [2/5] WORKDIR /app                                                                            1.2s 
+ => [3/5] COPY package.json ./                                                                    0.1s 
+ => [4/5] RUN npm install                                                                         6.6s 
+ => [5/5] COPY . .                                                                                0.2s 
+ => exporting to image                                                                            0.4s 
+ => => exporting layers                                                                           0.3s 
+ => => writing image sha256:bb89b0646be41055287fdac18ea1e405a2a19ef4b2919a0a02c213b9dc947b34      0.0s 
+ => => naming to docker.io/hurricanemark/localweather:1.0    
+```
+
+** List the image **
+
+```c
+PS D:\DEVEL\NODEJS\BrainUnscramblers\LocalWeather> docker image ls
+REPOSITORY                   TAG         IMAGE ID       CREATED         SIZE
+hurricanemark/localweather   1.0         bb89b0646be4   6 minutes ago   949MB
+```
+
+### Run docker
+
+Note that Dockerfile exposes port 8080.  This needs to be forwarded to a port on your local machine.  i.e. `LOCAL_PORT:CONTAINER_PORT` for example  *4321:8080*
+
+`docker run -p 4321:8080 bb89b0646be4`
+
+```c
+PS D:\DEVEL\NODEJS\BrainUnscramblers\LocalWeather> docker run -p 4321:8080 bb89b0646be4
+
+> LocalWeather@1.0.0 start /app
+> node app.js
+
+Local Weather is listening on port 8080
+```
+
+<br />
+
+To access the Local Weather app running in docker container, point your browser to the forwarding port 4321.
+
+`http:/localhost:4321`

index.js

@@ -27,7 +27,7 @@ app.post('/', (req, res) => {
     let city = req.body.locale;
     let url = process.env.WEATHER_VISUALCROSSING_API_BASE_URI;
 
-    /* https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Fremont%2C%20CA?unitGroup=us&contentType=json&key=E5PZ48U2C8EB6692GBD39U9LC */
+    /* https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Fremont%2C%20CA?unitGroup=us&contentType=json&key=apiKey */
     let uriStr = `${url}${city}?unitGroup=us&contentType=json&key=${apiKey}`;
     console.log(uriStr);
     request(uriStr, async function (err, response, body) {
@@ -62,6 +62,6 @@ let port = process.env.PORT || 3210;
 
 // creating a server that is listening on ${port} for connections.
 app.listen(port, () => {
-    console.log(`Staging app is listening on port ${port}`);
+    console.log(`StagingWeather report app is listening on port ${port}`);
 });
 

public/README.md

@@ -0,0 +1,163 @@
+# Core Logic
+
+To obtain the pinpoint weather data, earth location is a required parameter.  For this, the longitude and latitude would suffice programmatically.  For the interactive option, a physical postal address (partial address of City, State, or Country) is required.  Optionally, you could also register with the google map service (*additional charge will incur*).  Then, integrate google-map API where the user can point to a location on the map to trigger a localized weather report.
+
+* The geolocation of a known address can be obtained by using the client-side javascript [Windows Navigator](https://www.w3schools.com/jsref/obj_navigator.asp).  Your browser uses different types and sources of information to identify your location. These include your IP address, geolocation via HTML5 in your browser, and your PC's language and time settings.  For more detail on how Navigator.geolocation is determined, [read more here](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition).
+
+Sample code for client-side geolocation:
+
+```c
+    <script type=javascript>
+        if (navigator.geolocation) {
+            navigator.geolocation.getCurrentPosition(showPosition);
+        } else {
+            document.getElementById("geo-coord").innerHTML =
+            "Geolocation is not supported by this browser.";
+        }
+
+        function showPosition(position) {
+            document.getElementById("geo-coord").innerHTML =
+            "Latitude: " + position.coords.latitude +
+            "Longitude: " + position.coords.longitude;
+        }
+    </script>
+```
+
+* The API query for weather data can be describe as follow.
+
+    > <https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/LOCATION?unitGroup=metric&key=API_ACCESS_KEY&contentType=json>
+
+    Where, **LOCATION** can be City, State
+
+    and **API_ACCESS_KEY** can be obtained from registering with an API provider.
+
+* With the return JSON object representing the weather data, you wrap the individual data objects in a grid to make it user-friendly.
+
+<br />
+
+# Getting Real Data from A Paid API Provider
+
+Replace freecodecamp proxy URI (file: public/scripts.js) for weather data provider via a paid subscription. In this project, you can use the API service from the [VisualCrossing.com](https://www.visualcrossing.com).  The good news is if you registered to use the free tier, a good fit for demonstration purposes, there is no charge as long as you stay within the allowed call limit.  Read [here](https://www.visualcrossing.com/resources/blog/five-easy-weather-api-calls-to-get-the-weather-data-you-need/) to learn ways to make weather API calls.
+
+<br />
+
+# Steps to Integrate A New API Provider
+
+1. Register with a weather reporting service.  Consult with their API documentation on how to call their APIs.
+2. Obtain the API access key from the same provider above.
+3. Build an API https query and manually test it out.
+4. Write an async function to incorporate the API call and retrieve the weather data.
+
+
+> On the server, the `API_KEY` is hidden in the `.env` file.  By design, environment variables are not accessible to the client. For the client to directly query weather data, the API_KEY has to be available on the browser.  This will break the security of our application!
+
+**Options**:
+
+* Make the API calls on the server-side and then send response containing the weather data to the client;
+* or, require the client to use their own API keys;
+* or, using the serverless option with locked down to a service.  *This bad option multiplies your cost as your user base grows*.
+
+**Decision:**  
+
+You would want to live free and die harder, let's make the client calls the server which in turn requests weather data and sends responses back.  The client then can parse the response into a grid for display.  This means the server will need to provide GET requests!
+
+---
+
+**Options**: 
+
+You need to implement a middleware to retrieve weather data and serve it to the client using either
+- `EJS` embedded templates 
+- or `ReactJS`.
+
+Obviously, many developers have accountered this issue.  Lucky for us, `EJS`, `ReactJS` typically solves this problem.  EJS is an easier choice having less of a learning curve.
+
+**Decision:**  
+Let's introduce the Embedded Javascript ([EJS](https://www.npmjs.com/package/ejs)) middleware template rendering weather data upon client requestt.
+
+e.g. 
+```c
+    app.post("/geoLngLatWeather", (req, res) => {...})
+
+    app.get("/geoLngLatWeather", (req, res) => {...})
+
+    app.get("/physicalAddrWeather", (req, res, next) => {...})
+```
+<br />
+
+<strong><span style="color:gray; font-size:18px"> Staying within the Free Tier Limit</span> </strong>
+
+A typical free daily allowance cycle consists of up to 1000 free API queries.  In this case, the user has to wait until the beginning of the next free tier cycle.  To avoid being charged, this source code has a *a server-side accounting logic* to pause querying the weathercrossing API once its periodic allowance has been reached.  Unpause is automatic once the clock rolls to the beginning of a new daily free tier cycle.
+
+>*Potential development needed to notify the server admin if demands grew and if there are ways to monetize it.*
+
+<strong><span style="color:gray; font-size:18px">Caching the Weather Data</span></strong>
+
+Weather forecast data from `visualcrossing.com` typically contains information spanning 15 days, each day contains 24 hourly objects.  Additional queries within the same period would usually result in the same data.  We need to cache this information so as not to incur needless and sometimes costly API calls.  
+
+We could elect to use the DOM Storage API, also called the [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API) methods: `Window.sessionStorage` where data persists as long as the session is running, or `Window.localStorage` which has no expiration.  Note: when the last private tab is closed, data stored in the localStorage object of a site opened in a private tab or incognito mode is cleared.
+
+<br />
+
+<span style="color:green">**IMPORTANT:**</span>  Web Storage API needs to be implemented on the browser side (client with the DOM).  In this case, we make sure to place the javascript script at the bottom of the HTML body section.
+
+>Another option is to use no-sql storage such as `redis`.  A topic not in the scope of this exercise.  
+
+A sample of Web Storage API test:
+
+```c
+/* client-side script */
+    <script type=javascript>
+        function storageAvailable(type) {
+            let storage;
+            try {
+                storage = window[type];
+                const x = '__storage_test__';
+                storage.setItem(x, x);
+                storage.removeItem(x);
+                return true;
+            }
+            catch (e) {
+                return e instanceof DOMException && (
+                    // everything except Firefox
+                    e.code === 22 ||
+                    // Firefox
+                    e.code === 1014 ||
+                    // test name field too, because code might not be present
+                    // everything except Firefox
+                    e.name === 'QuotaExceededError' ||
+                    // Firefox
+                    e.name === 'NS_ERROR_DOM_QUOTA_REACHED') &&
+                    // acknowledge QuotaExceededError only if there's something already stored
+                    (storage && storage.length !== 0);
+            }
+        }
+
+        if (storageAvailable(methodString)) {
+            // Yippee! We can use localStorage awesomeness
+            // Save data to sessionStorage
+            sessionStorage.setItem("lw_name", "marcus");
+
+            // Get saved data from sessionStorage
+            let data = sessionStorage.getItem("lw_name");
+
+            alert(methodString +' says my name is ' + data);
+            // Remove saved data from sessionStorage
+            sessionStorage.removeItem("lw_name");
+        }
+        else {
+            // Too bad, no localStorage for us
+            alert(methodString + ' says Web Storage API is disabled.')
+        }
+    </script>
+```
+
+
+## Next Phases
+
+The followings are potential developments in subsequent iterations of this weather report project:
+
+* Integrate the server with auth0 and/or passport authentication
+
+* Registered members have access to a full-blown dashboard with maritime alerts, historical weather data, extended forecasts, etc.
+
+* Build and make mobile apps available to subscribed members.

public/Runtime.PNG

@@ -0,0 +1,6 @@
+# [EJS](https://www.npmjs.com/package/ejs) - Embedded Javascript Templates
+
+The `views` is where you keep all *.ejs files.  
+
+The `views/patials` folder is where you keep all ejs templates that meant for reusable code.
+