feat: cached egress rollout (supabase#37827)

Author: kevcodez

apps/docs/content/guides/database/extensions/wrappers/overview.mdx

@@ -92,7 +92,7 @@ This approach has several benefits:
 1. **On-demand:** analytical data is immediately available within your application with no additional infrastructure.
 1. **Always in sync:** since the data is queried directly from the remote server, it's always up-to-date.
 1. **Integrated:** large datasets are available within your application, and can be joined with your operational/transactional data.
-1. **Save on bandwidth:** only extract/load what you need.
+1. **Save on egress:** only extract/load what you need.
 
 ### Batch ETL with Wrappers
 

apps/docs/content/guides/platform/billing-faq.mdx

@@ -64,9 +64,11 @@ If you upgrade your project to a larger instance for 10 hours and then downgrade
 
 Read more about [Compute usage](/docs/guides/platform/manage-your-usage/compute).
 
-#### What is unified egress and how is it billed?
+#### What is egress and how is it billed?
 
-Unified egress refers to the total egress quota available to each organization. This quota can be utilized for various purposes such as Storage, Realtime, Auth, Functions, Supavisor, Log Drains and Database. Each plan includes a specific egress quota, and any additional usage beyond that quota is billed accordingly.
+Egress refers to the total bandwidth (network traffic) quota available to each organization. This quota can be utilized for various purposes such as Storage, Realtime, Auth, Functions, Supavisor, Log Drains and Database. Each plan includes a specific egress quota, and any additional usage beyond that quota is billed accordingly.
+
+We differentiate between cached (served via our CDN from cache hits) and uncached egress and give quotas for each type and have varying pricing (cached egress is cheaper).
 
 Read more about [Egress usage](/docs/guides/platform/manage-your-usage/egress).
 

apps/docs/content/guides/platform/manage-your-usage/egress.mdx

@@ -55,25 +55,29 @@ Data pushed to the connected log drain.
 
 **Example:** You set up a log drain, each log sent to the log drain is considered egress. You can toggle the GZIP option to reduce egress, in case your provider supports it.
 
+### Cached Egress
+
+Cached and uncached egress have independent quotas and independent pricing. Cached egress is egress that is served from our CDN via cache hits. Cached egress is typically incurred for storage through our [Smart CDN](/docs/guides/storage/cdn/smart-cdn).
+
 ## How charges are calculated
 
 Egress is charged by gigabyte. Charges apply only for usage exceeding your subscription plan's quota. This quota is called the Unified Egress Quota because it can be used across all services (Database, Auth, Storage etc.).
 
 ### Usage on your invoice
 
-Usage is shown as "Egress GB" on your invoice.
+Usage is shown as "Egress GB" and "Cached Egress GB" on your invoice.
 
 ## Pricing
 
-<Price price="0.09" /> per GB per month. You are only charged for usage exceeding your subscription plan's
-quota.
+<Price price="0.09" /> per GB per month for uncached egress, <Price price="0.03" /> per GB per month
+for cached egress. You are only charged for usage exceeding your subscription plan's quota.
 
-| Plan       | Unified Egress Quota | Over-Usage per month          |
-| ---------- | -------------------- | ----------------------------- |
-| Free       | 5 GB                 | -                             |
-| Pro        | 250 GB               | <Price price="0.09" /> per GB |
-| Team       | 250 GB               | <Price price="0.09" /> per GB |
-| Enterprise | Custom               | Custom                        |
+| Plan       | Egress Quota (Uncached / Cached) | Over-Usage per month (Uncached / Cached)                      |
+| ---------- | -------------------------------- | ------------------------------------------------------------- |
+| Free       | 5 GB / 5 GB                      | -                                                             |
+| Pro        | 250 GB / 250 GB                  | <Price price="0.09" /> per GB / <Price price="0.03" /> per GB |
+| Team       | 250 GB / 250 GB                  | <Price price="0.09" /> per GB / <Price price="0.03" /> per GB |
+| Enterprise | Custom                           | Custom                                                        |
 
 ## Billing examples
 
@@ -86,22 +90,24 @@ The organization's Egress usage is within the quota, so no charges for Egress ap
 | Pro Plan            | 1         | <Price price="25" />     |
 | Compute Hours Micro | 744 hours | <Price price="10" />     |
 | Egress              | 200 GB    | <Price price="0" />      |
+| Cached Egress       | 230 GB    | <Price price="0" />      |
 | **Subtotal**        |           | **<Price price="35" />** |
 | Compute Credits     |           | -<Price price="10" />    |
 | **Total**           |           | **<Price price="25" />** |
 
 ### Exceeding quota
 
-The organization's Egress usage exceeds the quota by 50 GB, incurring charges for this additional usage.
+The organization's Egress usage exceeds the uncached egress quota by 50 GB and the cached egress quota by 550 GB, incurring charges for this additional usage.
 
 | Line Item           | Units     | Costs                      |
 | ------------------- | --------- | -------------------------- |
 | Pro Plan            | 1         | <Price price="25" />       |
 | Compute Hours Micro | 744 hours | <Price price="10" />       |
 | Egress              | 300 GB    | <Price price="4.5" />      |
-| **Subtotal**        |           | **<Price price="39.5" />** |
+| Cached Egress       | 800 GB    | <Price price="16.5" />     |
+| **Subtotal**        |           | **<Price price="47.5" />** |
 | Compute Credits     |           | -<Price price="10" />      |
-| **Total**           |           | **<Price price="29.5" />** |
+| **Total**           |           | **<Price price="37.5" />** |
 
 ## View usage
 
@@ -118,7 +124,7 @@ You can view Egress usage on the [organization's usage page](https://supabase.co
   zoomable
 />
 
-In the Total Egress section, you can see the usage for the selected time period. Hover over a specific date to view a breakdown by service.
+In the Total Egress section, you can see the usage for the selected time period. Hover over a specific date to view a breakdown by service. Note that this includes the cached egress.
 
 <Image
   alt="Unified Egress"
@@ -128,6 +134,16 @@ In the Total Egress section, you can see the usage for the selected time period.
   }}
 />
 
+Separately, you can see the cached egress right below:
+
+<Image
+  alt="Unified Egress"
+  src={{
+    light: '/docs/img/guides/platform/cached-egress--light.png',
+    dark: '/docs/img/guides/platform/cached-egress.png',
+  }}
+/>
+
 ### Custom report
 
 1. On the [reports page](https://supabase.com/dashboard/project/_/reports), click **New custom report** in the left navigation menu
@@ -144,7 +160,7 @@ In the Total Egress section, you can see the usage for the selected time period.
 
 ## Debug usage
 
-To better understand your Egress usage, identify what’s driving the most traffic. Check the most frequent database queries, or analyze the most requested API paths to pinpoint high-bandwidth endpoints.
+To better understand your Egress usage, identify what’s driving the most traffic. Check the most frequent database queries, or analyze the most requested API paths to pinpoint high-egress endpoints.
 
 ### Frequent database queries
 

apps/docs/content/guides/storage/production/scaling.mdx

@@ -24,6 +24,10 @@ Using the browser cache can effectively lower your egress since the asset remain
 
 You have the option to set a maximum upload size for your bucket. Doing this can prevent users from uploading and then downloading excessively large files. You can control the maximum file size by configuring this option at the [bucket level](/docs/guides/storage/buckets/creating-buckets).
 
+#### Smart CDN
+
+By leveraging our [Smart CDN](/docs/guides/storage/cdn/smart-cdn), you can achieve a higher cache hit rate and therefore lower your egress cached, as we charge less for cached egress (see [egress pricing](/docs/guides/platform/manage-your-usage/egress#pricing)).
+
 ## Optimize listing objects
 
 Once you have a substantial number of objects, you might observe that the `supabase.storage.list()` method starts to slow down. This occurs because the endpoint is quite generic and attempts to retrieve both folders and objects in a single query. While this approach is very useful for building features like the Storage viewer on the Supabase dashboard, it can impact performance with a large number of objects.

apps/docs/content/guides/storage/serving/bandwidth.mdx

@@ -8,44 +8,52 @@ sidebar_label: 'Bandwidth & Storage Egress'
 
 ## Bandwidth & Storage egress
 
-Free Plan Organizations in Supabase have a limit of 5 GB of bandwidth. This limit is calculated by the sum of all the data transferred from the Supabase servers to the client. This includes all the data transferred from the database, storage, and functions.
+Free Plan Organizations in Supabase have a limit of 10 GB of bandwidth (5 GB cached + 5 GB uncached). This limit is calculated by the sum of all the data transferred from the Supabase servers to the client. This includes all the data transferred from the database, storage, and functions.
 
-### Checking Storage egress requests in Logs Explorer:
+### Checking Storage egress requests in Logs Explorer
 
 We have a template query that you can use to get the number of requests for each object in [Logs Explorer](/dashboard/project/_/logs/explorer/templates).
 
 ```sql
 select
-  r.method as http_verb,
-  r.path as filepath,
+  request.method as http_verb,
+  request.path as filepath,
+  (responseHeaders.cf_cache_status = 'HIT') as cached,
   count(*) as num_requests
 from
   edge_logs
-  cross join unnest(metadata) as m
-  cross join unnest(m.request) as r
-  cross join unnest(r.headers) as h
-where (path like '%storage/v1/object/%' or path like '%storage/v1/render/%') and r.method = 'GET'
-group by r.path, r.method
+  cross join unnest(metadata) as metadata
+  cross join unnest(metadata.request) as request
+  cross join unnest(metadata.response) as response
+  cross join unnest(response.headers) as responseHeaders
+where
+  (path like '%storage/v1/object/%' or path like '%storage/v1/render/%')
+  and request.method = 'GET'
+group by 1, 2, 3
 order by num_requests desc
 limit 100;
 ```
 
 Example of the output:
 
-```
+```json
 [
-    {"filepath":"/storage/v1/object/sign/large%20bucket/20230902_200037.gif",
-    "http_verb":"GET",
-    "num_requests":100
-    },
-    {"filepath":"/storage/v1/object/public/demob/Sports/volleyball.png",
-    "http_verb":"GET",
-    "num_requests":168
-    }
+  {
+    "filepath": "/storage/v1/object/sign/large%20bucket/20230902_200037.gif",
+    "http_verb": "GET",
+    "cached": true,
+    "num_requests": 100
+  },
+  {
+    "filepath": "/storage/v1/object/public/demob/Sports/volleyball.png",
+    "http_verb": "GET",
+    "cached": false,
+    "num_requests": 168
+  }
 ]
 ```
 
-### Calculating egress:
+### Calculating egress
 
 If you already know the size of those files, you can calculate the egress by multiplying the number of requests by the size of the file.
 You can also get the size of the file with the following cURL:
@@ -67,6 +75,6 @@ Total Egress = 395.76MB
 
 You can see that these values can get quite large, so it's important to keep track of the egress and optimize the files.
 
-### Optimizing egress:
+### Optimizing egress
 
-If you are on the Pro Plan, you can use the [Supabase Image Transformations](/docs/guides/storage/image-transformations) to optimize the images and reduce the egress.
+See our [scaling tips for egress](/docs/guides/storage/production/scaling#egress).

apps/docs/content/guides/storage/serving/image-transformations.mdx

@@ -259,7 +259,7 @@ response = supabase.storage.from_('bucket').download(
 
 When using the image transformation API, Storage will automatically find the best format supported by the client and return that to the client, without any code change. For instance, if you use Chrome when viewing a JPEG image and using transformation options, you'll see that images are automatically optimized as `webp` images.
 
-As a result, this will lower the bandwidth that you send to your users and your application will load much faster.
+As a result, this will lower the egress that you send to your users and your application will load much faster.
 
 <Admonition type="note">
 

apps/docs/content/guides/telemetry/reports.mdx

@@ -270,7 +270,7 @@ The Storage report provides visibility into how your Supabase Storage is being u
 | --------------- | ------------------------------------------ | ------------------------------------------------------ |
 | Total Requests  | Overall request volume to Storage          | Traffic patterns and usage trends                      |
 | Response Speed  | Average response time for storage requests | Performance bottlenecks and optimization opportunities |
-| Network Traffic | Ingress and egress bandwidth usage         | Data transfer costs and CDN effectiveness              |
+| Network Traffic | Ingress and egress usage                   | Data transfer costs and CDN effectiveness              |
 | Request Caching | Cache hit rates and miss patterns          | CDN performance and cost optimization                  |
 | Top Routes      | Most frequently accessed storage paths     | Popular content and usage patterns                     |
 
@@ -305,5 +305,5 @@ The API Gateway report analyzes traffic patterns and performance characteristics
 | Total Requests  | Overall API request volume                | Traffic patterns and growth trends               |
 | Response Errors | Error rates with 4XX and 5XX status codes | API reliability and user experience issues       |
 | Response Speed  | Average API response times                | Performance bottlenecks and optimization targets |
-| Network Traffic | Request and response bandwidth usage      | Data transfer patterns and cost implications     |
+| Network Traffic | Request and response egress usage         | Data transfer patterns and cost implications     |
 | Top Routes      | Most frequently accessed API endpoints    | Usage patterns and optimization priorities       |

apps/docs/content/troubleshooting/all-about-supabase-egress-a_Sg_e.mdx

@@ -31,4 +31,10 @@ While pointing out the exact cause for egress may not be straightforward, there
 - Reduce the number of queries/calls by optimising client code or use caches to reduce the number of requests/queries being done: https://github.com/psteinroe/supabase-cache-helpers/
 - In case of update/insert queries, if you don’t need the entire row to be returned, configure your ORM/queries to not return the entire row
 - In case of running manual backups through Supavisor, remove unneeded tables and/or reduce the frequency
-- For Storage, if you start using the [Smart CDN](https://supabase.com/docs/guides/storage/cdn/smart-cdn) Storage Egress usage can be managed. You can also use the [Supabase Image Transformations](https://supabase.com/docs/guides/storage/image-transformations) to optimize the images and reduce the egress.
+- For Storage, if you start using the [Smart CDN](https://supabase.com/docs/guides/storage/cdn/smart-cdn) Storage Egress usage can be reduced. You can also use the [Supabase Image Transformations](https://supabase.com/docs/guides/storage/image-transformations) to optimize the images and reduce the egress.
+
+**Cached vs uncached egress**
+
+We differentiate between cached and uncached egress. Cached egress refers to egress that is served via our CDN and hits the cache. Uncached egress, on the other hand, refers to egress that is not served from the cache and requires a fresh request to the origin server.
+
+Your plan includes a quota for both cached and uncached egress and these are independent. Cached egress is also cheaper in case you exceed your quota.

apps/docs/features/docs/Reference.navigation.client.tsx

@@ -214,7 +214,7 @@ export function RefLink({
         <Link
           ref={ref}
           // We don't use these links because we never do real navigation, so
-          // prefetching just wastes bandwidth
+          // prefetching just wastes egress
           prefetch={false}
           href={href}
           className={getLinkStyles(isActive, className)}