From 88c9bfa99a546a7a3b0cc523d5b0e05a8f244401 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Birm=C3=A9?= Date: Tue, 2 May 2023 14:15:04 +0200 Subject: [PATCH] chore: fixed reade merge conflict --- README.md | 334 ++---------------------------------------------------- 1 file changed, 12 insertions(+), 322 deletions(-) diff --git a/README.md b/README.md index d3022ef..7374507 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ -<<<<<<< HEAD

Chaos Stream Proxy

@@ -66,6 +65,17 @@ To try it out, go to your favourite HLS/MPEG-DASH video player such as `https:// | `statusCode` | Replace the response for a specific segment request with a specified status code response | | `timeout` | Force a timeout for the response of a specific segment request | +### Load Manifest url params from AWS SSM parameter store instead +- Create a .env file at the root the of project +- fill it like this : +``` +AWS_REGION="eu-central-1" +AWS_SSM_PARAM_KEY="/ChaosStreamProxy/Development/UrlParams" +LOAD_PARAMS_FROM_AWS_SSM=true +``` +- on AWS SSM, create a parameter with name : /ChaosStreamProxy/Development/UrlParams +- add a value for corruptions, for example : &statusCode=[{i:3,code:500},{i:4,code:500}] + ## Corruptions Currently, the Chaos Stream Proxy supports 3 types of corruptions for HLS and MPEG-DASH streams. These corruptions may be used in combination with one another. @@ -280,324 +290,4 @@ Eyevinn Technology is an independent consultant firm specialized in video and st At Eyevinn, every software developer consultant has a dedicated budget reserved for open source development and contribution to the open source community. This give us room for innovation, team building and personal competence development. And also gives us as a company a way to contribute back to the open source community. -Want to know more about Eyevinn and how it is to work here? Contact us at work@eyevinn.se! -======= -# Chaos Stream Proxy (V1) - -A server that acts as middle hand for manifest and segment requests, with the ability of adding corruptions to the manifest file, or messing with segment requests. - -It parses the query parameters from the request and applies corruptions as specified. - -Currently supported stream formats: - -- HLS -- MPEG-DASH (MPD) - -If you want to try it out, a demo version is available at `https://chaos-proxy.prod.eyevinn.technology`. - -## Get Started - -Requires `NodeJS` v14+ and `npm` - -### For Development - -`npm install` installs dependencies. - -`npm run dev` starts the server on port `8000`. - -Run on a custom port by setting the `PORT` environment variable. - -To try it out, go to your favourite HLS/MPEG-DASH video player such as `https://web.player.eyevinn.technology/index.html` and paste the proxied URL. For example, if the source / original manifest is located at: `https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8` the proxied URL is `http://localhost:8000/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8`. - -## API - -| ENDPOINT | METHOD | DESCRIPTION | -| ------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | -| `/api/v2/manifests/hls/proxy-master.m3u8` | GET | Returns a proxy Multivariant M3U8 file, based on query parameters | -| `/api/v2/manifests/hls/proxy-media.m3u8` | GET | Returns a proxy Media M3U8 file, based on query parameters | -| `/api/v2/manifests/dash/proxy-master.mpd` | GET | Returns a proxy MPD file, based on query parameters | -| `/api/v2/manifests/dash/proxy-segment` | GET | Applies corruption present in query parameter and may return a 302 redirect to the original segment file | -| `/api/v2/segments/proxy-segment` | GET | Applies corruption present in query parameter and may return a 302 redirect to the original segment file | -| `/` | GET | Server health check | - -### Query Parameters - -| PARAMETER | DESCRIPTION | -| ------------ | ----------------------------------------------------------------------------------------- | -| `url` | Url path to the original HLS/MPEG-DASH stream (REQUIRED) | -| `delay` | Delay the response, in milliseconds, for a specific segment request | -| `statusCode` | Replace the response for a specific segment request with a specified status code response | -| `timeout` | Force a timeout for the response of a specific segment request | - -## Corruptions - -Currently, the Chaos Stream Proxy supports 3 types of corruptions for HLS and MPEG-DASH streams. These corruptions may be used in combination with one another. - -### Specifying Corruption Configurations - -To specify the configurations for a particular corruption, you will need to add a stringified JSON object as a query parameter to the proxied URL. -Each corruption has a unique configuration JSON object template. Each object can be used to target one specific segment for corruption. -e.i. `https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=?some_corruption=[{i:0},{i:1},{i:2}, ... ,{i:N}]` - -Across all coruptions, there are 2 ways to target a segment in a playlist for corruption. - -1. `i`: The segment's list index in any Media Playlist, with HLS segments starting at 0 and MPEG-DASH segments starting at 1. For a Media Playlist with 12 segments, `i`=11, would target the last segment for HLS and `i`=12, would target the last segment for MPEG-DASH. -2. `sq`: The segment's Media Sequence Number (**HLS only**). For a Media Playlist with 12 segments, and where `#EXT-X-MEDIA-SEQUENCE` is 100, `sq`=111 would target the last segment. When corrupting a live HLS stream it is recommended to target with `sq`. - -Below are configuration JSON object templates for the currently supported corruptions. A query should have its value be an array consisting of any one of these 3 types of items: - -Delay Corruption: - -```typescript -{ - i?: number | "*", // index of target segment in playlist. If "*", then target all segments. (Starts on 0 for HLS / 1 for MPEG-DASH) - sq?: number | "*", // media sequence number of target segment in playlist. If "*", then target all segments - ms?: number, // time to delay in milliseconds - br?: number | "*", // apply only to specific bitrate -} -``` - -Status Code Corruption: - -```typescript -{ - i?: number | "*", // index of target segment in playlist. If "*", then target all segments. (Starts on 0 for HLS / 1 for MPEG-DASH) - sq?: number | "*", // media sequence number of target segment in playlist. If "*", then target all segments - code?: number, // code to return in http response status header instead of media file - br?: number | "*", // apply only to specific bitrate -} -``` - -Timeout Corruption: - -```typescript -{ - i?: number | "*", // index of target segment in playlist. If "*", then target all segments. (Starts on 0 for HLS / 1 for MPEG-DASH) - sq?: number | "*", // media sequence number of target segment in playlist. If "*", then target all segments - br?: number | "*", // apply only to specific bitrate -} -``` - -One can either target a segment through the index parameter, `i`, or the sequence number parameter, `sq`. In the case where one has entered both, the **index parameter** will take precedence. - -When targeting all segments through the input value of `"*"`, it is possible to **untarget** a specific segment by including a JSON item with only either `i` or `sq` in the corruption array, see example corruption #4. - -### Example corruptions on HLS Streams: - -1. VOD: With segment timeout on third segment: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&timeout=[{i:2}] -``` - -2. VOD: With segment delay of 3000ms on first and second segment: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&delay=[{i:0,ms:3000},{i:1,ms:3000}] -``` - -3. VOD: With response of status code 404 on all segments: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&statusCode=[{i:*,code:404}] -``` - -4. VOD: With segment delay of 500ms on all segments (except for third and seventh segment): - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&delay=[{i:*,ms:500},{i:2},{i:6}] -``` - -5. VOD: With segment delay of 1500ms on fifth segment, response code 404 on sixth, and timeout on seventh: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&delay=[{i:4,ms:1500}]&statusCode=[{i:5,code:404}]&timeout=[{i:9}] -``` - -6. VOD: With segment delay of 1500ms on sixth segment, followed by a response code 400 if the bitrate is 2426000: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8&delay=[{i:5,ms:1500}]&statusCode=[{i:5,code:400,br:2426000}] - -``` - -7. LIVE: With response of status code 404 on segment with sequence number 105: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/hls/proxy-master.m3u8?url=https://cph-p2p-msl.akamaized.net/hls/live/2000341/test/master.m3u8&statusCode=[{sq:105,code:400}] -``` - -### Example corruptions on MPEG-DASH Streams -1. VOD: Example of MPEG-DASH with delay of 1500ms and response code 418 on second segment: -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/dash/proxy-master.mpd?url=https://f53accc45b7aded64ed8085068f31881.egress.mediapackage-vod.eu-north-1.amazonaws.com/out/v1/1c63bf88e2664639a6c293b4d055e6bb/64651f16da554640930b7ce2cd9f758b/66d211307b7d43d3bd515a3bfb654e1c/manifest.mpd&delay=[{i:2,ms:1500}]&statusCode=[{i:2,code:418}] -``` - -2. VOD: Example of MPEG-DASH with response code 404 on third segment: -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/dash/proxy-master.mpd?url=https://f53accc45b7aded64ed8085068f31881.egress.mediapackage-vod.eu-north-1.amazonaws.com/out/v1/1c63bf88e2664639a6c293b4d055e6bb/64651f16da554640930b7ce2cd9f758b/66d211307b7d43d3bd515a3bfb654e1c/manifest.mpd&statusCode=[{i:3,code:404}] -``` - -3. VOD: Example of MPEG-DASH with segment delay of 1500ms on all segments (except for first and second segment): -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/dash/proxy-master.mpd?url=https://f53accc45b7aded64ed8085068f31881.egress.mediapackage-vod.eu-north-1.amazonaws.com/out/v1/1c63bf88e2664639a6c293b4d055e6bb/64651f16da554640930b7ce2cd9f758b/66d211307b7d43d3bd515a3bfb654e1c/manifest.mpd&delay=[{i:*,ms:1500},{i:1},{i:2}] -``` - -## Development Environment - -To deploy and update development environment create and push a tag with the suffix `-dev`, for example `my-feat-test-dev`. If you run `npm run deploy:dev` it will automatically create a tag based on git revision with the `-dev` suffix and push it. - -## Production Environment - -To deploy and update production environment publish a release on GitHub. This will trigger and initiate the workflow to build image and update the production cluster. - -## Technology Stack - -[NodeJS](https://nodejs.org/en/) and [Fastify](https://www.fastify.io/). - -## GIT Ways of Working - -In the interest of keeping a clean and easy to debug git history, use the following guidelines: - -- Read [How to Write a Commit Message](https://chris.beams.io/posts/git-commit/). -- Follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) specification (this differs a bit from the recommendations in the above link) -- A commit should contain a single change set -- A commit should pass tests, linting, and build - -### Feature Branches - -To start working on a feature, create a [feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). - -`git checkout -b your-name/the-feature` - -Make a pull request when it is ready for review. - -### Commitlint Hook - -Commit messages are automatically linted via [husky](https://github.com/typicode/husky). - -## Scripts - -Check `package.json` for available scripts. - -## Optionnal Features -### Load Manifest url params from aws ssm parameter store instead -- Create a .env file at the root the of project -- fill it like this : -``` -AWS_REGION="eu-central-1" -AWS_SSM_PARAM_KEY="/ChaosStreamProxy/Development/UrlParams" -LOAD_PARAMS_FROM_AWS_SSM=true -``` -- on AWS SSM, create a parameter with name : /ChaosStreamProxy/Development/UrlParams -- add a value for corruptions, for example : &statusCode=[{i:3,code:500},{i:4,code:500}] - -## Commercial Options - -The Chaos Stream Proxy is released as open source but we do offer some commercial options in relation to it. Contact sales@eyevinn.se if you are interested for pricing and more information. - -### Hosting - -We host the service in our environment for a monthly recurring fee. Included is business hours support on a best effort basis. - -### Deployment - -We help you deploy and integrate the service in your environment on a time-of-material basis. - -### Feature Development - -When you need a new feature developed and does not have the capacity or competence of your own to do it, we can on a time-of-material introduce this feature in the current code base and under the current open source license. - -### Professional Services and Development - -When you need help with building for example integration adaptors or other development in your code base related to this open source project we can offer a development team from us to help out on a time-of-material basis. - - -## License (Apache-2.0) - -``` -Copyright 2022 Eyevinn Technology AB - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` - -## About Eyevinn Technology - -Eyevinn Technology is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor. - -At Eyevinn, every software developer consultant has a dedicated budget reserved for open source development and contribution to the open source community. This give us room for innovation, team building and personal competence development. And also gives us as a company a way to contribute back to the open source community. - -Want to know more about Eyevinn and how it is to work here? Contact us at work@eyevinn.se! ->>>>>>> 9552919 (clean docker file,) -

- Chaos Stream Proxy -

- -
- Chaos Stream Proxy - Introduce predictable and reproducable errors in a stream -
-
-
- -
-
- -[![github release](https://img.shields.io/github/v/release/Eyevinn/chaos-stream-proxy?style=flat-square)](https://github.com/Eyevinn/chaos-stream-proxy/releases) -[![license](https://img.shields.io/github/license/eyevinn/chaos-stream-proxy.svg?style=flat-square)](LICENSE) - -[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=flat-square)](https://github.com/eyevinn/chaos-stream-proxy/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) -[![made with hearth by Eyevinn](https://img.shields.io/badge/made%20with%20%E2%99%A5%20by-Eyevinn-59cbe8.svg?style=flat-square)](https://github.com/eyevinn) -[![Slack](http://slack.streamingtech.se/badge.svg)](http://slack.streamingtech.se) - -
-| ENDPOINT | METHOD | DESCRIPTION | -| ----------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | -| `/api/v2/manifests/hls/proxy-master.m3u8` | GET | Returns a proxy Multivariant M3U8 file, based on query parameters | -| `/api/v2/manifests/hls/proxy-media.m3u8` | GET | Returns a proxy Media M3U8 file, based on query parameters | -| `/api/v2/manifests/dash/proxy-master.mpd` | GET | Returns a proxy MPD file, based on query parameters | -| `/api/v2/manifests/dash/proxy-segment` | GET | Applies corruption present in query parameter and may return a 302 redirect to the original segment file | -| `/api/v2/segments/proxy-segment` | GET | Applies corruption present in query parameter and may return a 302 redirect to the original segment file | -| `/` | GET | Server health check | - - - - -4. LIVE: Example of uncompressed MPEG-DASH live stream with response of status code 404 on segment with sequence number 3447425: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/dash/proxy-master.mpd?url=https://d2fz24s2fts31b.cloudfront.net/out/v1/3b6879c0836346c2a44c9b4b33520f4e/manifest.mpd&statusCode=[{sq:3447425, code:404}] -``` - -5. LIVE: Example of compressed MPEG-DASH live stream with response of status code 404 on segment with time sequence number 841164350: - -``` -https://chaos-proxy.prod.eyevinn.technology/api/v2/manifests/dash/proxy-master.mpd?url=https://livesim.dashif.org/livesim/testpic_2s/Manifest.mpd&statusCode=[{sq:841164350, code:404}] -``` - -## Contributing -See [CONTRIBUTING](CONTRIBUTING.md) if you want to contribute to this project. - -### Git way-of-working -## Optionnal Features -### Load Manifest url params from aws ssm parameter store instead -- Create a .env file at the root the of project -- fill it like this : -``` -AWS_REGION="eu-central-1" -AWS_SSM_PARAM_KEY="/ChaosStreamProxy/Development/UrlParams" -LOAD_PARAMS_FROM_AWS_SSM=true -``` - -We help you deploy and integrate the service in your environment on a time-of-material basis. -When you need a new feature developed and does not have the capacity or competence of your own to do it, we can on a time-of-material introduce this feature in the current code base and under the current open source license. -When you need help with building for example integration adaptors or other development in your code base related to this open source project we can offer a development team from us to help out on a time-of-material basis. +Want to know more about Eyevinn and how it is to work here? Contact us at work@eyevinn.se! \ No newline at end of file