Watt Time v3 Support

casdk-docs/docs/architecture/decisions/0016-watt-time-v3.md

@@ -0,0 +1,62 @@
+
+# 0015. WattTime v3 Changes
+
+## Status
+
+Proposed
+
+## Context
+As part of the update to Watt Time v3 we are proposing the changes to the underlying API calls.  This needs to be tracked so we understand the impacts, and if multiple options are available, which option was selected and why.
+
+This wll impact the `CarbonAware.DataSources.WattTime` project primarily.
+
+## Decision
+
+The proposal is for the outlined WattTime API mapping and changes.
+
+## WattTime v2, v3 Mapping
+
+The following document and guidelines was used to understand the impact to the Carbon Aware SDK for the WattTime v3 updates.  https://docs.watttime.org/#tag/Transitioning-from-APIv2-to-APIv3 
+
+### Base URL
+The base URL will need to change.
+> TODO: Add where this is configured 
+
+|Base URL (v2) | Based URL (v3) | 
+|---|---|
+| /v2 | /v3 |
+
+
+### Paths
+The paths will also need to change. 
+
+The following is configured at  `CarbonAware.DataSources.WattTime/src/Constants/Paths.cs`
+
+| API Endpoint | Description | Path (v2) | Path (v3) | Notes |
+|--------------|-------------|-----------|-----------|---|
+| Data         | Get data    | /data     | /historical          |  _Request_ <li> `starttime` is now `start` and mandatory <li> `endtime` is now `end` and mandatory <li> `ba` is now `region` <li> `signal_type` added <br> _Response_ <li> `signal_type` added
+| Forecast     | Get forecast| /forecast | /forecast   | **TODO: CHECK IMPACT** <br> No longer be used for historical data <br> _Request_ <li> `ba` is now `region` <li> `extended_forecast` removed <li> `horizon_hours` added  <li> `signal_type` added <li> Historical forecasts are now at `/forecast/historical` <br> _Response_ <li> `signal_type` added 
+| Historical   | Get historical forecast data | /historical (?) | /forecast/historical (?)           | **We need to validate why historical was being used for the API, and what historical used to be, and whether this should be the new /forecast/historical or not.**
+| Balancing Authority From Location | Get balancing authority from location | /ba-from-loc | /region-from-loc          | Check if the CA SDK uses BA at all <br><br> _Request_ <li> `name` is now `region_full_name` <li> `abbrev` is now `region` <li> `signal_type` added <br> _Response_ <li> `id` removed <li> `signal_type` added  | 
+| Login        | User login  | https://api2.watttime.org/v2/login    | https://api.watttime.org/login | Path has changed from being version specific to being no longer related to the API version.  <br><br> NOTE: Updated in wattTime client to now have 2 HTTP clients to decouple versions from the login. 
+
+### Query Strings
+
+#### Signal Type
+Everything call takes an optional `signal_type` parameter that defaults to `co2_moer`.  
+
+The following comes from `CarbonAware.DataSources.WattTime/src/Constants/QueryStrings.cs` and the changes are consistent with the discussion above.
+
+| Query String (v2)                   | Query String if Changed (v3)                 | Description                  |
+|------------------------------------|----------------------------------|------------------------------|
+| `ba`                                 | `region`                                 | Balancing Authority / Region |
+| `starttime`                          | `start`                                | Start Time                       |
+| `endtime`                            | `end`                                 | End Time                         |
+| `latitude`                           | -                                 | Latitude                         |
+| `longitude`                          | -                                 | Longitude                        |
+| `username`                           | -                                 | Username                         |
+
+## Green Impact  
+
+Neutral
+

src/CarbonAware.CLI/test/integrationTests/Commands/EmissionsForecasts/EmissionsForecastsCommandTests.cs

@@ -99,7 +99,7 @@ public async Task EmissionsForecasts_RequestedAtOptions_ReturnsExpectedData()
         IgnoreTestForDataSource("data source does not implement '--requested-at'", DataSourceType.ElectricityMaps);
 
         // Arrange
-        _dataSourceMocker.SetupBatchForecastMock();
+        _dataSourceMocker.SetupHistoricalBatchForecastMock();
 
         // Act
         var exitCode = await InvokeCliAsync($"emissions-forecasts -l eastus -r 2022-09-01");

src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/mock/ElectricityMapDataSourceMocker.cs

@@ -126,7 +126,7 @@ public void SetupDataMock(DateTimeOffset start, DateTimeOffset end, string locat
         SetupResponseGivenGetRequest(Paths.PastRange, pastRange);
     }
 
-    public void SetupBatchForecastMock()
+    public void SetupHistoricalBatchForecastMock()
     {
         throw new NotImplementedException();
     }

src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/src/ElectricityMapsDataSource.cs

@@ -72,7 +72,7 @@ private static EmissionsForecast ToEmissionsForecast(Location location, Forecast
     }
 
     /// <inheritdoc />
-    public async Task<EmissionsForecast> GetCarbonIntensityForecastAsync(Location location, DateTimeOffset requestedAt)
+    public async Task<EmissionsForecast> GetHistoricalCarbonIntensityForecastAsync(Location location, DateTimeOffset requestedAt)
     {
         await Task.Run(() => true);
         throw new NotImplementedException();

src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMapsFree/mock/ElectricityMapsFreeDataSourceMocker.cs

@@ -49,7 +49,7 @@ public void SetupForecastMock()
         throw new NotImplementedException();
     }
 
-    public void SetupBatchForecastMock()
+    public void SetupHistoricalBatchForecastMock()
     {
         throw new NotImplementedException();
     }

src/CarbonAware.DataSources/CarbonAware.DataSources.Json/mock/JsonDataSourceMocker.cs

@@ -42,7 +42,7 @@ public void Initialize() { }
     public void Reset() { }
     public void Dispose() { }
 
-    public void SetupBatchForecastMock()
+    public void SetupHistoricalBatchForecastMock()
     {
         throw new NotImplementedException();
     }

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/mock/WattTimeDataSourceMocker.cs

@@ -1,6 +1,6 @@
-using CarbonAware.Interfaces;
-using CarbonAware.DataSources.WattTime.Constants;
+using CarbonAware.DataSources.WattTime.Constants;
 using CarbonAware.DataSources.WattTime.Model;
+using CarbonAware.Interfaces;
 using System.Net;
 using System.Net.Mime;
 using System.Text.Json;
@@ -13,11 +13,11 @@ internal class WattTimeDataSourceMocker : IDataSourceMocker
 {
     protected WireMockServer _server;
 
-    private static readonly BalancingAuthority defaultBalancingAuthority = new()
+    private static readonly RegionResponse defaultRegion = new()
     {
-        Id = 12345,
-        Abbreviation = "TEST_BA",
-        Name = "Test Balancing Authority"
+        Region = "TEST_REGION",
+        RegionFullName = "Test Region Full Name",
+        SignalType = SignalTypes.co2_moer
     };
 
     private static readonly LoginResult defaultLoginResult = new() { Token = "myDefaultToken123" };
@@ -26,6 +26,8 @@ public WattTimeDataSourceMocker()
     {
         _server = WireMockServer.Start();
         Environment.SetEnvironmentVariable("DataSources__Configurations__WattTime__BaseURL", _server.Url!);
+        Environment.SetEnvironmentVariable("DataSources__Configurations__WattTime__AuthenticationBaseUrl", _server.Url!);
+
         Initialize();
     }
 
@@ -39,20 +41,31 @@ public void SetupDataMock(DateTimeOffset start, DateTimeOffset end, string locat
         {
             var newDataPoint = new GridEmissionDataPoint()
             {
-                BalancingAuthorityAbbreviation = defaultBalancingAuthority.Abbreviation,
                 PointTime = pointTime,
                 Value = 999.99F,
                 Version = "1.0",
-                Datatype = "dt",
                 Frequency = 300,
                 Market = "mkt",
             };
 
+
             data.Add(newDataPoint);
             pointTime = newDataPoint.PointTime + duration;
         }
 
-        SetupResponseGivenGetRequest(Paths.Data, JsonSerializer.Serialize(data));
+        var meta = new GridEmissionsMetaData()
+        {
+            Region = defaultRegion.Region,
+            SignalType = SignalTypes.co2_moer
+        };
+
+        var gridEmissionsResponse = new GridEmissionsDataResponse()
+        {
+            Data = data,
+            Meta = meta
+        };
+
+        SetupResponseGivenGetRequest(Paths.Data, JsonSerializer.Serialize(gridEmissionsResponse));
     }
 
     public void SetupForecastMock()
@@ -63,15 +76,13 @@ public void SetupForecastMock()
         var start = new DateTimeOffset(((curr.Ticks + d.Ticks - 1) / d.Ticks) * d.Ticks, TimeSpan.Zero);
         var end = start + TimeSpan.FromDays(1.0);
         var pointTime = start;
-        var ForecastData = new List<GridEmissionDataPoint>();
+        var forecastData = new List<GridEmissionDataPoint>();
         var currValue = 200.0F;
 
         while (pointTime < end)
         {
             var newForecastPoint = new GridEmissionDataPoint()
             {
-                BalancingAuthorityAbbreviation = defaultBalancingAuthority.Abbreviation,
-                Datatype = "dt",
                 Frequency = 300,
                 Market = "mkt",
                 PointTime = start,
@@ -80,32 +91,39 @@ public void SetupForecastMock()
             };
             newForecastPoint.PointTime = pointTime;
             newForecastPoint.Value = currValue;
-            ForecastData.Add(newForecastPoint);
+            forecastData.Add(newForecastPoint);
             pointTime = pointTime + TimeSpan.FromMinutes(5);
             currValue = currValue + 5.0F;
         }
 
-        var forecast = new Forecast()
+        var meta = new GridEmissionsMetaData()
         {
-            ForecastData = ForecastData,
+            Region = defaultRegion.Region,
+            SignalType = SignalTypes.co2_moer,
             GeneratedAt = new DateTimeOffset(2022, 1, 1, 0, 0, 0, TimeSpan.Zero)
         };
-        SetupResponseGivenGetRequest(Paths.Forecast, JsonSerializer.Serialize(forecast));
+
+        var forecastResponse = new ForecastEmissionsDataResponse()
+        {
+            Data = forecastData,
+            Meta = meta
+        };
+
+
+        SetupResponseGivenGetRequest(Paths.Forecast, JsonSerializer.Serialize(forecastResponse));
     }
 
-    public void SetupBatchForecastMock()
+    public void SetupHistoricalBatchForecastMock()
     {
         var start = new DateTimeOffset(2021, 9, 1, 8, 30, 0, TimeSpan.Zero);
         var end = start + TimeSpan.FromDays(1.0);
         var pointTime = start;
-        var ForecastData = new List<GridEmissionDataPoint>();
+        var forecastData = new List<GridEmissionDataPoint>();
         var currValue = 200.0F;
         while (pointTime < end)
         {
             var newForecastPoint = new GridEmissionDataPoint()
             {
-                BalancingAuthorityAbbreviation = defaultBalancingAuthority.Abbreviation,
-                Datatype = "dt",
                 Frequency = 300,
                 Market = "mkt",
                 PointTime = start,
@@ -114,19 +132,41 @@ public void SetupBatchForecastMock()
             };
             newForecastPoint.PointTime = pointTime;
             newForecastPoint.Value = currValue;
-            ForecastData.Add(newForecastPoint);
+            forecastData.Add(newForecastPoint);
             pointTime = pointTime + TimeSpan.FromMinutes(5);
             currValue = currValue + 5.0F;
         }
 
-        var forecastData = new List<Forecast> {
-            new Forecast()
+        var meta = new GridEmissionsMetaData()
+        {
+            Region = defaultRegion.Region,
+            SignalType = SignalTypes.co2_moer,
+            GeneratedAt = new DateTimeOffset(2022, 1, 1, 0, 0, 0, TimeSpan.Zero)
+        };
+
+        //var forecastBatchData = new List<ForecastEmissionsDataResponse> {
+        //    new ForecastEmissionsDataResponse()
+        //    {
+        //        Data = forecastData,
+        //        Meta = meta
+        //    }
+        //};
+
+        var historicalForecastResponse = new HistoricalForecastEmissionsDataResponse()
+        {
+            Data = new List<HistoricalEmissionsData>()
             {
-                ForecastData = ForecastData,
-                GeneratedAt = new DateTimeOffset(2022, 1, 1, 0, 0, 0, TimeSpan.Zero)
-            }
+                new HistoricalEmissionsData()
+                {
+                    Forecast = forecastData,
+                    GeneratedAt = new DateTimeOffset(2099, 1, 1, 0, 0, 0, TimeSpan.Zero)
+                }
+            },
+            Meta = meta
         };
-        SetupResponseGivenGetRequest(Paths.Forecast, JsonSerializer.Serialize(forecastData));
+
+
+        SetupResponseGivenGetRequest(Paths.ForecastHistorical, JsonSerializer.Serialize(historicalForecastResponse));
     }
 
     public void Initialize()
@@ -156,8 +196,8 @@ private void SetupResponseGivenGetRequest(string path, string body)
                     .WithBody(body)
         );
     }
-    private void SetupBaMock(BalancingAuthority? content = null) =>
-        SetupResponseGivenGetRequest(Paths.BalancingAuthorityFromLocation, JsonSerializer.Serialize(content ?? defaultBalancingAuthority));
+    private void SetupBaMock(RegionResponse? content = null) =>
+        SetupResponseGivenGetRequest(Paths.RegionFromLocation, JsonSerializer.Serialize(content ?? defaultRegion));
 
     private void SetupLoginMock(LoginResult? content = null) =>
         SetupResponseGivenGetRequest(Paths.Login, JsonSerializer.Serialize(content ?? defaultLoginResult));