Implement new Concept Exercise: net/http

[junedev]

Getting Started

If you have not yet contributed to concept exercises before, this task requires some upfront reading to acquire the necessary background knowledge.

Here you can read about what Concept Exercises are and how they are structured:

• What are Concept Exercises?
• Concept Exercises
• Concepts

If you have not done so yet, it is probably also helpful to do a couple of "Learning Exercises" (this is how they are called on the site) yourself. You can also look at the code of an existing concept exercise like welcome-to-tech-palace for reference.

Also be aware of these general guidelines.

• Exercism Markdown Specification
• Exercism Formatting and Style Guide

Goal

The goal here is to create a new concept exercise to teach how to use Go's built-in http server.
The concept and exercise need to be written from scratch.

Concepts

The following concept needs to be created. You can use the introduction.md file of the concept also as introduction.md file of the exercise. No need to create different content at this point. Additionally, if you want to save some time it is ok to not have an extensive about.md for now. It can also be mainly the introduction.md content, maybe with some additions you would like to make.

• http

Learning Objectives

In the concepts the student should learn about the following topics and then practice them in the concept exercise.

• ... [tbd]

Out of Scope

• ... [tbd]

Prerequisites

• ... [tbd]

Other prerequisites should be added as needed to solve the specific exercise.

Story Idea

It's a good idea for concept exercises to have a story that gives some flair and context to the tasks.
Create a new story for this exercise. The story doesn't need to be highly complex, even a small story goes a long way to make the tasks more interesting. For some inspiration for the story, check the other exercises on the track or the page Exercism docs: Stories for an overview of stories used across tracks.

[junedev]

This issue is claimed by @MikaeelMF.

[andrerfcsantos]

@MikaeelMF Just bouncing some ideas about this. There was discussion about if it would be possible to have a client program communicate with a server program on localhost (eventually server and client can be the same program). Asking around, it seems that this is possible.

Our containers run with networking disabled --network none and I did a little test to see if this could influence the capacity of a client and server to communicate on localhost and this seems to not be the case - a client and a server can still communicate on localhost even with --network none.

For reference, this is what I used to test this: simple-client-server.zip

I thought of this idea of a client and a server because I'm imagining that if the exercise wants to teach about sending requests, our tests might want to start a server to validate the request the student does. The same if we want to teach about servers, probably the tests might act as a client to validate the server.

With this I don't want necessarily to force the exercise into a particular direction - just exploring some options :)

[MikaeelMF]

@MikaeelMF Just bouncing some ideas about this. There was discussion about if it would be possible to have a client program communicate with a server program on localhost (eventually server and client can be the same program). Asking around, it seems that this is possible.

Our containers run with networking disabled --network none and I did a little test to see if this could influence the capacity of a client and server to communicate on localhost and this seems to not be the case - a client and a server can still communicate on localhost even with --network none.

For reference, this is what I used to test this: simple-client-server.zip

I thought of this idea of a client and a server because I'm imagining that if the exercise wants to teach about sending requests, our tests might want to start a server to validate the request the student does. The same if we want to teach about servers, probably the tests might act as a client to validate the server.

With this I don't want necessarily to force the exercise into a particular direction - just exploring some options :)

Thanks @andrerfcsantos for checking this out! My initial ideas are exactly revolving around testing solutions using a client/server structure as well.

[MikaeelMF]

Getting Started

If you have not yet contributed to concept exercises before, this task requires some upfront reading to acquire the necessary background knowledge.

Here you can read about what Concept Exercises are and how they are structured:

• What are Concept Exercises?
• Concept Exercises
• Concepts

If you have not done so yet, it is probably also helpful to do a couple of "Learning Exercises" (this is how they are called on the site) yourself. You can also look at the code of an existing concept exercise like welcome-to-tech-palace for reference.

Also be aware of these general guidelines.

• Exercism Markdown Specification
• Exercism Formatting and Style Guide

Goal

The goal here is to create a new concept exercise to teach how to use Go's built-in http server. The concept and exercise need to be written from scratch.

Concepts

The following concept needs to be created. You can use the introduction.md file of the concept also as introduction.md file of the exercise. No need to create different content at this point. Additionally, if you want to save some time it is ok to not have an extensive about.md for now. It can also be mainly the introduction.md content, maybe with some additions you would like to make.

• http

Learning Objectives

In the concepts the student should learn about the following topics and then practice them in the concept exercise.

• ... [tbd]

Out of Scope

• ... [tbd]

Prerequisites

• ... [tbd]

Other prerequisites should be added as needed to solve the specific exercise.

Story Idea

It's a good idea for concept exercises to have a story that gives some flair and context to the tasks. Create a new story for this exercise. The story doesn't need to be highly complex, even a small story goes a long way to make the tasks more interesting. For some inspiration for the story, check the other exercises on the track or the page Exercism docs: Stories for an overview of stories used across tracks.

Great! Thank you for the instructions.

[MikaeelMF]

Learning Objectives:

The general objective is to get someone who knows nothing about network programming to start to get curious and get introduced to resources to follow up on given subjects if they wish to learn more. Therefore I have tried to give a short introduction on the following topics:

1. what is HTTP?
2. What makes a client request in HTTP?
3. What makes a server response in HTTP?
4. How to use the go net/http package to write a basic HTTP client?
5. How to use the go net/http package to write a basic HTTP server?

Out of Scope:

Since this is an introduction, I will not go into any detail about the http headers. Also, it does not seem beneficiary to explain all request methods.
Also on the implementation side, I don't think it is a good idea to explain the defer, io.Reader, and io.Writer in this exercise. Since these concepts are used in the network programming using net/http quite a lot, it would have been great if we currently had these concepts taught in the roadmap. Labeling these concepts as a prerequisite seems a bit overboard but not talking about them anywhere in the roadmap might make things a little bit difficult to fully understand this exercise. I would really appreciate it if you could let me know what you think is the best path to take here.

---

I think a basic version of the concept introduction will be available in the coming days, when it is representable, I will create a PR and set it as a draft, so anyone who wishes to participate or take a look at it and suggest new ideas would do so easily.

Please do not hold back any suggestions that you may have, I would truly appreciate it if you share with me any ideas or thoughts of yours on this topic.

[junedev]

@MikaeelMF Please keep in mind that Exercism concepts/concept exercises are always about "How to do X in language Y? (for someone that already knows X)". They are not about "What is X?". In this case that means 1-3 would not be part of the concept, the concept would only be about 4+5 (How to make an http request in Go? How to set up an http server in Go?). For 1-3 you can say some brief introductory words and include links for people that are not yet familiar with the topic in general. In the future, we will have out own Exercism wide content for explaining these general programming concepts but it will take a while until we get there.

As part of 5, I would recommend to explain how Go uses Go routines so that the code in an http handler can be written in a synchronous fashion without blocking any other requests from being processed.

Since the scope of the learning objectives is now reduced, maybe you have space to include setting headers. Might be a good idea.

Regarding io.Reader/io.Writer: Handwaving over something a little bit to keep the scope of the concept/exercise managable is totally fine. Also that some some prerequisite concept is not available yet happens quite often. You can still go ahead with your concept though. What we do in the JavaScript track in these cases is that we include links where people can read up on those things. Then later when the concept exists within the Syllabus, we replace the links to external resources with links to the Exercism concept.

[MikaeelMF]

@MikaeelMF Please keep in mind that Exercism concepts/concept exercises are always about "How to do X in language Y? (for someone that already knows X)". They are not about "What is X?". In this case that means 1-3 would not be part of the concept, the concept would only be about 4+5 (How to make an http request in Go? How to set up an http server in Go?). For 1-3 you can say some brief introductory words and include links for people that are not yet familiar with the topic in general. In the future, we will have out own Exercism wide content for explaining these general programming concepts but it will take a while until we get there.

As part of 5, I would recommend to explain how Go uses Go routines so that the code in an http handler can be written in a synchronous fashion without blocking any other requests from being processed.

Since the scope of the learning objectives is now reduced, maybe you have space to include setting headers. Might be a good idea.

Regarding io.Reader/io.Writer: Handwaving over something a little bit to keep the scope of the concept/exercise managable is totally fine. Also that some some prerequisite concept is not available yet happens quite often. You can still go ahead with your concept though. What we do in the JavaScript track in these cases is that we include links where people can read up on those things. Then later when the concept exists within the Syllabus, we replace the links to external resources with links to the Exercism concept.

Ah I see!
Thank you for letting me know!
I will change my outline to better match exercism policies!

[MikaeelMF]

I have created a draft PR for this issue. I have written the client section and would really appreciate it if you could look at it and share your thoughts and ideas with me.

P.S. I don't know if it is OK to create a draft PR and check things step-by-step in exercism, so please let me know if it is against here's working manners and I will close the PR right away. I just thought the concept will become more robust and better this way.

[andrerfcsantos]

@MikaeelMF It would help if in the description of the PR you could add some indication of the status of the PR. With this I mean a brief list of things you consider done (hence we can give feedback on), what is in progress and what is planned. This makes us avoid giving feedback on something that is not finished and avoid suggestions of things you've already planned.

[MikaeelMF]

@MikaeelMF It would help if in the description of the PR you could add some indication of the status of the PR. With this I mean a brief list of things you consider done (hence we can give feedback on), what is in progress and what is planned. This makes us avoid giving feedback on something that is not finished and avoid suggestions of things you've already planned.

Oh My bad! I will do so right away!

Update: I have added a To-Do list to explain things that I have decided to do, and things that are included as well. Also, I will update it as soon as I decide on new topics for other sections.

[MikaeelMF]

I have completed my To-Do list for sections that I am going to cover about the server. I initially wanted to cover middlewares as well but figured maybe it becomes too long and also is not really beneficial to the general goals of the concept.
Please let me know if there are any sections that you believe must be discussed and it is missing from my list.

[MikaeelMF]

Hi!
Just wanted to let you know that the main text for introduction is completed. I just need to do some formatting and add the appropriate reference for a code snippet that I've used. So I would appreciate it if you would check it out and see if anything comes to your mind that is missing.

[MikaeelMF]

I have fixed the formatting based on exercism guidelines and I think the content is ready to get merged.
Only one problem that I have encountered for using configlet to change the main config.json, I couldn't install it using the script in go/bin. I encounter error "curl: (23) Failure writing output to destination".(btw I'm using a macOS 12.4)

[junedev]

I commented in the PR.

Re the configlet issue: Please ask about your issue in our Slack space or here https://github.com/exercism/configlet/issues. I don't use mac so I can't help with that. (As mentioned in the PR, this issue does not block you from working on the PR.)